You are not logged in.

#1 2020-06-05 20:04:18

QuietMisdreavus
Member
From: Denver, CO
Registered: 2020-06-05
Posts: 6
Website

Adding HTML docs to `git` package? (PKGBUILD review request)

Git can build its documentation in man, info, or HTML format. Currently, the git package in [extra] only builds and packages the man pages, but it's possible to also build in the HTML documentation as well. I've checked out the PKGBUILD for git from the ABS and modified it to build and install the HTML docs alongside the man pages:

$ diff ~/abs/git/trunk/PKGBUILD ~/builds/git/PKGBUILD
61c61
<     all man
---
>     all doc
97c97
<     install install-man
---
>     install install-man install-html

After running makepkg with this modification, the resulting package had both man pages and HTML pages, and after installing it was possible to use either one by passing "-w" or "-m" flags to "git help".

If modifying the "git" package is not desired, it's also possible to grab the HTML docs by themselves - kernel.org also packages "git-htmldocs-$pkgver.tar.xz" alongside the source code archives. This would allow a separate "git-htmldocs" package to be created, and those who don't want the extra filesystem use of the HTML pages on their system wouldn't have to pay for it.

Is there any support for this idea? I would love to be able to browse local Git documentation in browser tabs, and this change doesn't seem to be that major, at least in terms of PKGBUILD diff size.

Last edited by QuietMisdreavus (2020-06-06 00:07:43)


ghost on the internet
twitter: @QuietMisdreavus // mastodon: @QuietMisdreavus@squad.town

Offline

#2 2020-06-05 20:07:24

Slithery
Forum Moderator
From: Norfolk, UK
Registered: 2013-12-01
Posts: 3,950

Re: Adding HTML docs to `git` package? (PKGBUILD review request)

You could always create the git-htmldocs package yourself and upload it to the AUR.


No, it didn't "fix" anything. It just shifted the brokeness one space to the right. - jasonwryan
Closing -- for deletion; Banning -- for muppetry. - jasonwryan

aur - dotfiles

Offline

#3 2020-06-05 20:10:30

QuietMisdreavus
Member
From: Denver, CO
Registered: 2020-06-05
Posts: 6
Website

Re: Adding HTML docs to `git` package? (PKGBUILD review request)

I almost did that, then realized i could add them to the actual git package, and i wasn't sure whether that would fall afoul of the "don't repackage anything in the official repos" or "if this is a shortcoming of an official package, report a bug instead" rules of the AUR submission guidelines. If that doesn't seem like a big deal, though, i could get started on that.


ghost on the internet
twitter: @QuietMisdreavus // mastodon: @QuietMisdreavus@squad.town

Offline

#4 2020-06-06 00:07:06

QuietMisdreavus
Member
From: Denver, CO
Registered: 2020-06-05
Posts: 6
Website

Re: Adding HTML docs to `git` package? (PKGBUILD review request)

I've gone ahead and worked up a PKGBUILD for a potential git-htmldocs package. I'd appreciate any tips to improve it. One thing i'm uncertain about is what should go into the dependencies. I've listed git as a dependency, but that's not strictly true. On the other hand, listing zero dependencies whatsoever also seems strange, so i'm not sure what the best practice would be.

Here's the PKGBUILD:

# Maintainer: Victoria Mitchell <email elided>
pkgname=git-htmldocs
pkgver=2.27.0
pkgrel=1
pkgdesc="HTML documentation files for Git"
arch=('any')
url="https://git-scm.com/"
license=('GPL2')
groups=()
depends=('git')
makedepends=()
checkdepends=()
optdepends=()
source=("https://www.kernel.org/pub/software/scm/git/$pkgname-$pkgver.tar."{xz,sign})
sha256sums=('ffa91681b6a8f558745924b1dbb76d604c9e52b27c525c6bd470c0123f7f4af3'
            'SKIP')
# all of the files in the archive can be extracted directly into the documentation dir, so extract
# it manually
noextract=("$pkgname-$pkgver.tar.xz")
validpgpkeys=('96E07AF25771955980DAD10020D04E5A713660A7') # Junio C Hamano
options=(!strip) # there are no binaries in the archive to strip

prepare() {
    mkdir -p "$srcdir/$pkgname-$pkgver"
    bsdtar -xf "$pkgname-$pkgver.tar.xz" -C "$srcdir/$pkgname-$pkgver"

    # the files in the archive all have mode 600 (folders 700) so reset those before copying in
    find "$srcdir/$pkgname-$pkgver" -type d -exec chmod 755 \{\} \+
    find "$srcdir/$pkgname-$pkgver" -type f -exec chmod 644 \{\} \+
}

package() {
    mkdir -p "$pkgdir"/usr/share/doc
    cp -a -r "$srcdir/$pkgname-$pkgver" "$pkgdir"/usr/share/doc/git-doc
}

ghost on the internet
twitter: @QuietMisdreavus // mastodon: @QuietMisdreavus@squad.town

Offline

#5 2020-06-10 09:35:01

FernandoBasso
Member
From: Brazil
Registered: 2010-10-27
Posts: 87
Website

Re: Adding HTML docs to `git` package? (PKGBUILD review request)

@QuietMisdreavus

I miss HTML man pages too. Thanks for the AUR package.


There is a difference between knowing the path and walking the path.

Offline

#6 2020-06-10 09:44:29

jplatte
Member
Registered: 2020-06-10
Posts: 1
Website

Re: Adding HTML docs to `git` package? (PKGBUILD review request)

Re. PKGBUILD best practices: I don't think I've seen the strip option disabled for packages without binaries, though I guess it also does no harm.

Installation of the files should probably be done with install over cp, then you can skip the permission resetting step from prepare too. In this case, I'm not sure prepare is needed at all. I don't exactly understand your comment above the noextract, how is the location you're extracting the files into with bsdtar better than the default?

Offline

#7 2020-06-10 15:12:47

QuietMisdreavus
Member
From: Denver, CO
Registered: 2020-06-05
Posts: 6
Website

Re: Adding HTML docs to `git` package? (PKGBUILD review request)

jplatte wrote:

Re. PKGBUILD best practices: I don't think I've seen the strip option disabled for packages without binaries, though I guess it also does no harm.

This was mainly just a personal-preference thing, since the strip step of the package process added several seconds of (what i thought was) worthless work, especially when i was debugging it and already had the source files downloaded. I figured it wouldn't be that big a deal to remove it, but i do agree that i does feel unconventional.

jplatte wrote:

Installation of the files should probably be done with install over cp, then you can skip the permission resetting step from prepare too. In this case, I'm not sure prepare is needed at all. I don't exactly understand your comment above the noextract, how is the location you're extracting the files into with bsdtar better than the default?

The archive as downloaded from kernel.org doesn't have a subfolder in the tarball. So if i left the noextract line out, "$srcdir" would have the dozens of documentation files, right alongside the tar.xz and signature file. There wouldn't be a "$pkgname-$pkgver" folder to cd into like how loads of other PKGBUILDs do. If i copied in everything from "$srcdir" into "$pkgdir", i would have to either fish the downloaded source files out, or do something else to figure out how to only copy the contents of the archive and not the archive itself.

Also i couldn't figure out how to get install to work, partly due to the permissions on the files and partly because i wasn't sure how to make it act equivalently to that cp command.


ghost on the internet
twitter: @QuietMisdreavus // mastodon: @QuietMisdreavus@squad.town

Offline

#8 2020-06-10 15:53:27

Trilby
Inspector Parrot
Registered: 2011-11-29
Posts: 24,247
Website

Re: Adding HTML docs to `git` package? (PKGBUILD review request)

QuietMisdreavus wrote:

Also i couldn't figure out how to get install to work, partly due to the permissions on the files and partly because i wasn't sure how to make it act equivalently to that cp command.

You don't want it to act exactly like cp, that's the point.  Do you really want to install all the .txt files too?  To install the html from the current directory:

install -Dm644 -t "$pkgdir/usr/share/doc/git-doc" *.html

"UNIX is simple and coherent..." - Dennis Ritchie, "GNU's Not UNIX" -  Richard Stallman

Offline

#9 2020-06-10 21:05:11

QuietMisdreavus
Member
From: Denver, CO
Registered: 2020-06-05
Posts: 6
Website

Re: Adding HTML docs to `git` package? (PKGBUILD review request)

Trilby wrote:
QuietMisdreavus wrote:

Also i couldn't figure out how to get install to work, partly due to the permissions on the files and partly because i wasn't sure how to make it act equivalently to that cp command.

You don't want it to act exactly like cp, that's the point.  Do you really want to install all the .txt files too?  To install the html from the current directory:

install -Dm644 -t "$pkgdir/usr/share/doc/git-doc" *.html

This works perfectly, thanks! I guess the *.txt files aren't really necessary (though i did hesitate about the release notes that are included, i left those out too since they're not accessible via "git help"), so it shrinks the package down a bit. Here's the updated PKGBUILD. I feel like this is a bit easier to understand:

# Maintainer: Victoria Mitchell <email elided>
pkgname=git-htmldocs
pkgver=2.27.0
pkgrel=2
pkgdesc="HTML documentation files for Git"
arch=('any')
url="https://git-scm.com/"
license=('GPL2')
groups=()
depends=('git')
makedepends=()
checkdepends=()
optdepends=()
source=("https://www.kernel.org/pub/software/scm/git/$pkgname-$pkgver.tar."{xz,sign})
sha256sums=('ffa91681b6a8f558745924b1dbb76d604c9e52b27c525c6bd470c0123f7f4af3'
            'SKIP')
validpgpkeys=('96E07AF25771955980DAD10020D04E5A713660A7') # Junio C Hamano
options=(!strip) # there are no binaries in the archive to strip

package() {
    install -Dm644 -t "$pkgdir/usr/share/doc/git-doc" *.html
    install -Dm644 -t "$pkgdir/usr/share/doc/git-doc/howto" howto/*.html
    install -Dm644 -t "$pkgdir/usr/share/doc/git-doc/technical" technical/*.html
}

ghost on the internet
twitter: @QuietMisdreavus // mastodon: @QuietMisdreavus@squad.town

Offline

#10 2020-06-11 02:17:28

eschwartz
Trusted User/Bug Wrangler
Registered: 2014-08-08
Posts: 3,622

Re: Adding HTML docs to `git` package? (PKGBUILD review request)

QuietMisdreavus wrote:
jplatte wrote:

Re. PKGBUILD best practices: I don't think I've seen the strip option disabled for packages without binaries, though I guess it also does no harm.

This was mainly just a personal-preference thing, since the strip step of the package process added several seconds of (what i thought was) worthless work, especially when i was debugging it and already had the source files downloaded. I figured it wouldn't be that big a deal to remove it, but i do agree that i does feel unconventional.

It's perfectly fine to use it, but I would usually see it for a package which had a LOT of files, to the point where checking each one of them to see if it is an ELF file becomes pretty slow. Most people and most packages just aren't bothersome enough in this regard, since it scales with the number of files being packaged.

Last edited by eschwartz (2020-06-11 02:18:33)


Managing AUR repos The Right Way -- aurpublish (now a standalone tool)

Offline

#11 2020-06-11 02:24:59

QuietMisdreavus
Member
From: Denver, CO
Registered: 2020-06-05
Posts: 6
Website

Re: Adding HTML docs to `git` package? (PKGBUILD review request)

eschwartz wrote:

It's perfectly fine to use it, but I would usually see it for a package which had a LOT of files, to the point where checking each one of them to see if it is an ELF file becomes pretty slow. Most people and most packages just aren't bothersome enough in this regard, since it scales with the number of files being packaged.

That makes sense, thanks! I'll take the "options" line out, then. The file count here doesn't approach the kind of scale you're implying, especially after taking the "*.txt" files out.


ghost on the internet
twitter: @QuietMisdreavus // mastodon: @QuietMisdreavus@squad.town

Offline

Board footer

Powered by FluxBB