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

[Dan Nicholson]

On Mon, Mar 14, 2011 at 1:39 PM, Gaetan Nadon <memsize at videotron.ca> wrote:
> 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.

That's a fair assessment. Putting the implementation details in the
manual means it's less generic. However, the changes you made didn't
remove the details, they just hardcoded them, potentially incorrectly.

> 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'm not really sure, but sessreg the program is the one actually using
utmp.h. It seems strange to "fix" the manual but not the program. As
far as I know, no one is complaining that sessreg is doing the wrong
thing.

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

If you're on linux, look at /usr/include/paths.h. These are standard
unix macros, and I'm not really sure why we wouldn't use them. If the
desire is to make the manual not expose these details, then let's not
replace them with hardcoded values. I haven't seen anyone complain
that they're wrong, though.

--
Dan