conditional man pages

[jubalh]

The upstream tarball ships with pre-made man pages.
However the content of the man pages is dependent on compile options.
For example: https://github.com/shadow-maint/shadow/blob/master/man/login.defs.d/CHFN_AUTH.xml#L31

So in case shadow is compiled with --with-libpam, man login.defs will not include the entry about CHFN_AUTH.

Some distributions however just use the pre-made man pages, meaning the man pages don't fit their installation exactly.

To use the right one it is necessary to compile with --enable-man and also have the following:

• xsltproc
• docbook 4
• docbook stylesheets
• xml2po

If one of the first three is not present at build time, it will silently switch --enable-man off.

So this bug report is about discussing whether shipping pre-made man pages is a good idea because they depend on conditions. And if yes, whether we should note somewhere that they are conditional so distributions are aware of it an choose to build them themselves.
Shipping them but adding a note has the benefits of not adding more build requirements as a must.

[hallyn]

Thanks for tracking this down. I think it best to continue shipping the pre-made pages, and put a note somewhere warning people. Do you have any good suggestions about where? Where would have been the first place you would have looked, that would have helped you save time? A new man/README.md?

[jubalh]

Yes, I think something like this is a good idea.
I will create a PR later.

[vapier]

i agree strongly that we want precompiled man-pages in releases (the tools needed to build aren't exactly common or light to install). however, i'd suggest we take a different long term approach here ...

what if the man pages always contained all the possible content regardless of compiled settings ? instead, we annotate the relevant sections as "pam specific" or "available when built with pam support" or something like that ? as it stands right now, in order to read man pages that cover a system, you have to be on that exact system reading its man pages. there's no way to consult docs on another system or via the web. if i'm debugging a system that is down or misbehaving, having to have another connection/session active on it just to run man is kind of a downer.

some (i expect reasonable or common scenarios):

• on a laptop ssh-ed into other systems -- open another local terminal to run man (latency will be much better than running on remote side), or open a web page with docs and read it there
• sitting at a rescue console trying to debug things -- i'll still use my laptop to reference things because getting another local console might not be feasible or that easy to navigate
• connected to an embedded device or a container server -- docs might not even be available on it

i understand that, by consulting documentation that isn't on the exact device i'm hacking on, there's a chance for version skew. but when you do releases, it's also possible to snapshot the release documentation, so that would be addressable.

[hallyn]

On Fri, Sep 08, 2017 at 12:44:58PM -0700, Mike Frysinger wrote: i agree strongly that we want precompiled man-pages in releases (the tools needed to build aren't exactly common or light to install). however, i'd suggest we take a different long term approach here ... what if the man pages always contained all the possible content regardless of compiled settings ? instead, we annotate the relevant sections as "pam specific" or "available when built with pam support" or something like that ? as it stands right now, in order to read man pages that cover a system, you have to be on that exact system reading its man pages. there's no way to consult docs on another system or via the web. if i'm debugging a system that is down or misbehaving, having to have another connection/session active on it just to run `man` is kind of a downer.

That does make sense.