[PATCH app-sessreg 0/4] Providing more platform information in the man page

[Gaetan Nadon]

On Mon, 2011-03-14 at 12:44 -0700, Dan Nicholson wrote:

> 
> I think if you're going to make this change here, you'd also want to
> make the change in sessreg.h and sessreg.c, right? The whole point of
> filenames.sed.c is to mirror the configuration in the actual program.
> Right now configure.ac checks for header files like lastlog.h to
> determine if lastlog will be used, but further it uses that system's
> particular definition of _PATH_LASTLOG. This could make the man page
> divergent from the program.
> 
> I'm not sure I see a lot of benefit in removing that flexibility. I
> realize that most users won't see any differences, but the
> compatibility is already there to find the paths from standard unix
> headers.
> 


I lost track of the details,  but there were two main issues with the
man pages:

The man pages reflect the configuration of the actual program. I see
this as a problem
rather than a helpful feature. Man pages are often read off the web. It
is particularly
bad for this program as the tone of the information in the man page
makes the user think
it provides all platform information. The program itself is platform
neutral such that it 
will not break given an option for the wrong platform.

I recall that the attempt to reflect the configuration of the program is
flawed.
Assumptions are made based on the presence of headers, but the reality
is more
complex. Headers may be there, but are obsolete depending on the system
version. In the MAC, the new interface is used to read/write and the old
interface
is maintained for read-only. There is no way to reflect that in the man
pages.

That's my general impression of the man pages. There are two opposing
views
in the man page. One that gives info on multiple platforms, and one that
customizes info based on the platform where it is built.

I chose to go with the first approach. I can accept the second approach,
but it would have to be implemented correctly which I don't think is
possible.
How can you handle the case where utmp.h is shipped on a platform where
the docs tell you not to use it?

I don't have much system knowledge, if you are convinced the current man
page
contains no errors on any platform, I am fine.

Thanks!








-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.x.org/archives/xorg-devel/attachments/20110314/85a88704/attachment-0001.htm>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 197 bytes
Desc: This is a digitally signed message part
URL: <http://lists.x.org/archives/xorg-devel/attachments/20110314/85a88704/attachment-0001.pgp>