[PATCH app-xdm 3/4] man: provide info even when features are missing at configuration time

[Mark Kettenis]

> From: Gaetan Nadon <memsize at videotron.ca>
> Reply-to: memsize at videotron.ca
> 
> On Sun, 2010-08-22 at 10:17 +0200, Mark Kettenis wrote:
> 
> > > There is no harm done in providing this information and stating when
> > > it is applicable.
> > 
> > I disagree.  
> > 
> 
> I don't have a strong opinion on that. Help me out with good
> examples on how other man pages deal with a situation where the
> content might vary based on the computer where the software is
> installed.  I think this is this only module in xorg that does
> that. If this is preferable, then perhaps other modules should do so
> as well. Some have several configure options.

Listing lots of options that are irrelevant for the system a user is
on, is confusing.  On the other hand, there is something to be said
for the documentation for a project that supports multiple platforms
to be sharable between those platforms.  I think I'd prefer the
former, but I can see that for a project like Xorg the latter makes
more sense.


> > > +This resource is valid only when the arc4random() function
> > > +has been detected at installation.
> > 
> > How should a non-technical know whether arc4random() is present on the
> > system?
> > 
> 
> Related to my question above, is that the role of the man page? A more
> common situation is platform information.
> Should the man page display only information relevant to the platform on
> which it is installed? My experience with past projects is that all
> information was given with some platform indication.

Whether that makes sense does depend on what platform indication is
given.  Users probably knows the Operating System they're running.  So
saying something like "This feature is only available on OpenBSD and
Mac OS X." is ok in my view.  But "This feature is only available on
systems that have the arc4random() function." isn't terribly helpful.
Now the problem is of course that giving an accurate list of Operating
systems and keeping it up to date is tricky, especisally in an
autoconfiscated world.  So autoconfiscating the man pages themselves,
like the current app-xdm module does, may not be such a bad idea after
all.

Cheers,

Mark