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

[Dan Nicholson]

On Mon, Mar 14, 2011 at 11:19 AM, Gaetan Nadon <memsize at videotron.ca> wrote:
> This series aims at improving the man page by providing platform information
> in a more consistent way. It does a good job of covering the System V vs BSD
> implementations (although silent on Linux) by describing and comparing both.
>
> This puts the reader in a mind set where information on all platforms is provided
> rather than being limited or customized to one specific platform. This is the
> appropriate strategy particularly given than the sessreg command it documents also
> works on all these platforms by gracefully handling options differences.
>
> Unfortunately, it diverges from this strategy when providing filenames
> and man pages references. The man page digs into the source code to provide
> filenames that are only relevant to the platform on which the man page is built,
> with the assumption that it will only be read there and not on the web, for example.
>
> It also makes assumptions based on headers found to suggest other man pages to read.
> Some of these assumptions are incorrect. It does not handle very well the utmp vs utmpx
> usage by platforms. I have not attempted to correct that but this is one more reason
> for not attempting to guess which one, or both, are used.
>
> This is a "core dump" of information I gathered from the various man pages on the web as
> well as other articles.
>
> SCO:            var/adm/utmp    var/adm/wtmp    var/adm/lastlog   utmp(5) ttys(5)
>                var/adm/utmpx   var/adm/wtmpx                     utmpx(5)
> Solaris:        var/adm/utmp    var/adm/wtmp    var/adm/lastlog   utmp(5)
>                var/adm/utmpx   var/adm/wtmpx                     utmpx(5)
> lastlog does not have a public interface and not mentioned in man pages
> In SCO, /etc/auth/system/ttys is not related to /etc/ttys.
> System V (including Linux) don't have ttys file
>
> Linux:          var/run/utmp    var/log/wtmp    var/log/lastlog  No ttys    utmp(5) utmpx(5) lastlog(5)
>
> OpenBSD:        var/run/utmp    var/log/wtmp    var/log/lastlog  /etc/ttys  utmp(5)  ttys(5)
> FreeBSD:        var/run/utmp    var/log/wtmp    var/log/lastlog  /etc/ttys  utmp(5)
> NetBSD:         var/run/utmp    var/log/wtmp    var/log/lastlog  /etc/ttys  utmp(5)  ttys(5)
>                var/run/utmpx   var/log/wtmpx   var/log/lastlogx            utmpx(5)
> MAC             var/run/utmp    var/log/wtmp    var/log/lastlog  /etc/ttys  utmp(5)  ttys(5)    deprecated
>                var/run/utmpx   backward        backward                    utmpx(5)     do not use utmp.h
> MAC has deprecated utmp and only uses utmpx but utmp files are still being used
>
> Gaetan Nadon (4):
>  man: computing the ttys file location is not required
>  man: SEE ALSO: computing the man pages to reference is not required
>  man: location of utmp/wtmp/lastlog files should not be computed
>  config: remove no longer used filenames.sed.c
>
>  man/Makefile.am     |   14 ++------------
>  man/filenames.sed.c |   29 -----------------------------
>  man/sessreg.man     |   25 ++++++++++++++++---------

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.

--
Dan