[lug] man pages in different distros

[Paul E Condon]

On Wed, Oct 15, 2003 at 05:06:08PM -0600, S.Coffin wrote:
> >> Are the man pages throughout the various distributions consistent or do
> >> they vary in content?  This came up the other day when a colleague was

They do vary in content, very much. For many basic programs, those in the
GNU distribution, the man page comes with the source from the writers of the
code. Many other pieces of software come without any man pages and the OS
packager, RH, Mandrake, etc. , provides the man page, either writing it or
cadging from somewhere else, possible even with proper attribution. A lot of
the man pages in the Debian distribution are edited by the Debian maintainer
to reflect changes to the software that are required by Debian's Policy, or
to improve the wording because the maintainer has tired of explaining how
the software really works to people filing bug reports. Presumeably, the
same, or similar, happens in other distributions


> >> getting some programs to run on a RH box.  He was having some trouble
> >> getting sort to work right and came in my office complaining about the
> >> lame sort man page when compared to the DEC sort man page.  I have to
> >> agree that the DEC man page had way more info and examples than the
> >> Linux man page.  I went to the meeting the other night and forgot to ask
> >> about this.
> 
> Not at all consistent.  Of course UNIX, Solaris, and Linux man pages
> will differ, and different versions of all these have different man
> pages as well.  Also, the GNU project attempted to convert all the man
> pages to "info" style, and consequently a lot of Linux man pages are
> no longer worth much.  In fact on my RH9, the "sort" man page states
> that "info sort" is the better documentation.

This is formulistic wording from the GNU project. Most software seems to 
have identical text for man and info. Many developers seem not to believe
that these two should be different, but POSIX places more strict format
requirements on man pages.

> 
> >> On sort...  My colleague was having trouble with the --key option.  We
> >> got it working, but I'm wondering if there is a typo in the man page?
> >> If I understand these things, the square brackets indicate optional
> >> arguments, but in the description of --key the left bracket is
> >> highlighted as if it's required.  To get it working we gave sort the
> >> following argument <-k4n,4n>.  It didn't work with just <-k4n>.  Seemed
> >> kind of strange to me since the second argument I believe is optional.
> 

The second argument is not* optional in POSIX compliant sort. Without the
second arg, the meaning is sort on fields 4 thru the end of record, treating
all these fields as numeric fields. For almost all situations, this is not
what you want. The two args option but without a second option, -s, also
might not be what you want. Without -s, sort looks for some 'last resort'
criterion for deciding the sort order when two records have the same value
for field 4. -s stands for 'stable sort'. Most texts on data management
assume stable sort as the default, but the program, sort, does not assume
this.

* Well, not quite 'not optional': It syntacticly optional, but with and
without the second field have different meanings. Similarly, the word
'not' is often syntactically optional in natural English. If a sentence
with a 'not' is syntactically correct, then the same sentence with the
'not' removed is also syntactically correct.



> Well, of course the final decision is how the command actually works, not
> what the doc says.  It is very possible that man pages have errors, and
> there are more errors as you get further generations away from the AT&T
> UNIX originals.  On my RH9 system, the command "sort -K4n" seems to work.
> 
> ps= Some of us were/are very offended that GNU attempted to dump the
> perfectly usable "man" format for the clunky "info" style.  Not only
> is the "info" user interface and texinfo source code inferior to the
> old way, but also re-writing the man pages introduced many errors.
> 
> 				=S.Coffin
> 				GV Computing
> 				scoffin at comcast.net
> 
> _______________________________________________
> Web Page:  http://lug.boulder.co.us
> Mailing List: http://lists.lug.boulder.co.us/mailman/listinfo/lug
> Join us on IRC: lug.boulder.co.us port=6667 channel=#colug

-- 
Paul E Condon           
pecondon at peakpeak.com