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

QuietMisdreavus · 2020-06-05 20:04:18

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)

Slithery · 2020-06-05 20:07:24

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

QuietMisdreavus · 2020-06-05 20:10:30

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.

QuietMisdreavus · 2020-06-06 00:07:06

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
}

FernandoBasso · 2020-06-10 09:35:01

@QuietMisdreavus

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

jplatte · 2020-06-10 09:44:29

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?

QuietMisdreavus · 2020-06-10 15:12:47

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.

Trilby · 2020-06-10 15:53:27

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

QuietMisdreavus · 2020-06-10 21:05:11

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
}

eschwartz · 2020-06-11 02:17:28

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)

QuietMisdreavus · 2020-06-11 02:24:59

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.

Arch Linux

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Board footer