search

shadow-maint / shadow

Upstream shadow tree
Other
287 stars 226 forks source link

Publish manpages online #872

Open nbraud opened 6 months ago

nbraud commented 6 months ago

Would it be possible to publish shadow's manpages online, as rendered to HTML? I'm aware many distros already have some central service to query all their manpages from, but it would be really useful to have a reference source to link that is distro-agnostic and faithful-to-upstream.

The implementation could be as simple as a GitHub action that automatically builds and publishes the manpages when they are pushed to master.

jubalh commented 6 months ago

Probably you are aware of the following, I just wanted to mention it for others as well:

it would be really useful to have a reference source to link that is distro-agnostic and faithful-to-upstream.

Be aware that some man pages are are only built when a certain configure flag is enabled/disabled (for example man5/limits.5, man1/getsubids.1). Additionally distributions might adapt man pages in case they change some settings in their packaging process. And man pages can change depending on the shadow version. So we might have to publish them for each release. Overall I think it's safer if people consult the man pages of their specific installation.

nbraud commented 6 months ago

Be aware that some man pages are are only built when a certain configure flag is enabled/disabled (for example man5/limits.5, man1/getsubids.1). Yes, I was (implicitly) assuming all manpages should be produced for an “online doc,” but that's a good point: those manpages do not state which configuration it's available in... which makes sense for pages meant to be consulted as-installed.

And man pages can change depending on the shadow version. So we might have to publish them for each release.

Yes, I didn't mention that above either, but it's not significantly harder to build a set of manpages per release.

Additionally distributions might adapt man pages in case they change some settings in their packaging process. [...] Overall I think it's safer if people consult the man pages of their specific installation.

I'm aware some distros do modify shadow quite extensively, which is why I wouldn't want to use the manpage from my particular system to discuss shadow in general (since I then have to check whether it's affected by distro's patches etc.)

(I did notice there were no pre-rendered manpages while doing some documentation for a distro, but in that case I agree the correct solution is to render & publish the manpage from the distro's packages)

alejandro-colomar commented 4 months ago

Hmmm, I already do that for the Linux man-pages (as a PDF book, not as HTML). See https://www.alejandro-colomar.es/share/dist/man-pages/git/HEAD/man-pages-HEAD.pdf; I have a git hook regenerating the PDF every time I push to the main branch. I also publish a PDF for every release; e.g., https://www.alejandro-colomar.es/share/dist/man-pages/6/6.06/man-pages-6.06.pdf.

I may do that for shadow stable releases and git HEAD, using the default configuration. The git hook will be in my server, to which I push manually, which means it may be a few commits behind GH, of course.

alejandro-colomar commented 3 months ago

https://www.alejandro-colomar.es/share/dist/shadow/git/HEAD/shadow-HEAD.pdf

The navigation index of the PDF has some problems. I've reported them to the author of the script, so hopefully that'll get fixed soon.

alejandro-colomar commented 3 months ago

And the 4.15.0 ones (this one is PGP-signed, as it's manually uploaded):

https://www.alejandro-colomar.es/share/dist/shadow/4/4.15/4.15.0/

alejandro-colomar commented 3 months ago

https://www.alejandro-colomar.es/share/dist/shadow/git/HEAD/shadow-HEAD.pdf

The navigation index of the PDF has some problems. I've reported them to the author of the script, so hopefully that'll get fixed soon.

Thanks to @DeriJames, we already have the PDF for the master branch with proper bookmarks (you can already find it in the link above).

https://lore.kernel.org/linux-man/ZfCAtl5Q-F2uPJM4@debian/T/#m8d20a678683625017a0a2e7c13c3ee2138893d54

I won't regenerate the PDF for 4.15.0, but any new versions will be built with the fixed script.

I could also publish the pages in the other languages, but I'd need to build Deri's branch of gropdf from source. I'll need to update the script to allow running a custom gropdf(1) that I'll install in /opt/local/.

Cheers, Alex

alejandro-colomar commented 3 months ago

Translations are now available at https://www.alejandro-colomar.es/share/dist/shadow/git/HEAD/man/.