Re: [9fans] Capitalization in man pages.

[Uriel <uriell@binarydream.org>]

On Wed, Dec 07, 2005 at 11:10:22PM -0500, Russ Cox wrote:
> Please don't rewrite all the man pages unless you first establish the
> value in doing so.  Converting from one troff macro package to another
> does not on first glance seem to offer any benefit at all.  In fact,
> things like man2html would then have to be updated, and no doubt all
> the errors introduced would have to be tracked down, and so on.  It
> hardly seems worth it, especially considering that the outward
> appearance would remain the same.
I partially agree, I see no reason to change macro package, but I do
think the outward appearance has to be changed and made consistent.
 
> On the other hand, checking that the man pages reflect
> reality (command line arguments, function signatures,
> and so on) would be genuinely useful.  I encouraged some
> others to do this a few years ago and they formed a group
> called the Plan 9 Documentation Task Force and fixed a
> few man pages but then I think they lost interest.

We looked at this some time ago, it's a rather tedious and long task,
but I still think it's worth doing(and it's in my TODO, maybe for when I
retire...)

One of the issues we found was that while the quality of the man pages
in general was very good, the way they structured information was very
inconsistent, with for example at least four different ways of listing
command line flags.

When we asked about this russ considered it overambitious to reword
every man page to have the same format and that it might "unnecessarily
remove the original authors style".

The style certainly deserves preserving because it's clear and to the
point, hats off to Rob that did an excellent job.

But I think it would be very good to have a set of clear guidelines
blessed by the original(or current) authors, for how pages belonging to
each section should be structured, and then make sure that every page
follows them. Some macros that help enforce this wouldn't hurt either,
but IMHO are optional.

For details about this effort see:
http://plan9.bell-labs.com/wiki/plan9/Man_pages_review/

> I made a bunch of updates to the plan9port man pages
> when I did the "first fully documented release" a year ago.
> Diffing those against the Plan 9 ones would be a good start.

Oksel did quite a bit of work on this, but I think he found it rather
frustrating. It was my hope that further deviations would be avoided in
the future, but I don't know what is the current state of things.

My suggestion at the time was to have identical man pages for p9p and
Plan 9, having an extra section describing p9p-only components, and
having a "PLAN 9 FROM USER SPACE" header describing any other
differences in individual man pages. Russ didn't like this.

uriel

P.S.: Some relevant quotes from email russ sent when this was being
discussed(BTW, I just double checked cfs(4) and the dashes for the
options are still missing both with man and man -P):
---
> We have not started the man pages review because we are unsure how much
> we should change, it would be nice to make the formating and structure
> of all man page more clear, consistent and uniform, but maybe we should
> limit ourselves to only fix obvious errors and omisions instead?

what about the formatting and structure do you believe is not clear,
consistent, and uniform?  (i can think of things, but i'd like to hear what
you think they are.)

i think it doesn't make sense to rewrite the man pages.  instead i think the
effort is much better spent making sure that everything is documented and
that the docs are up to date.  one good start would be to diff the plan9port
and the plan 9 man pages.  where they differ, the plan9port ones are newer
and should probably be copied back to plan 9.

there are lots of conventions for the writing of man pages, about formatting
and structure.  checkman.awk checks some of these, in particular the ordering
of sections, making sure that cross-referenced pages actually exist, and so
on.  other conventions are harder to check, like which names are in which
fonts, but those are pretty consistent.  see man(6) for details.
---
> most obviously: options (or flags).  some pages list flags in orderly
> fashion such as ls(1).  others do it likewise, but have no dash in
> front of the flags (e.g. cfs(4)).  this might be related to
> authorship.

huh?  cfs(4) has all the appropriate dashes.  i think maybe you are
looking at some crappy html version of the pages that occasionally omits
dashes.  try using man -P instead.

> yet other pages have no list of options but mention their meaning
> somewhere in the text (and then some even without dashes like
> tail(1)).
> the cfs(4) case is mostly aesthetic, for the tail(1) case it is hard
> to see the option you're looking for at a glance.

i agree that in some egregious cases, the options should be made more
obvious.  the f and r flags in tail(1) are a good example of this.

all pages should explicitly list all the options in the SYNOPSIS section
or should at least say [ options ] if the list is too long.

> but, it is better to just concentrate on accurate man pages.  we'll
> also look into plan9ports man pages (have not really used plan9ports).

yes.  i'd definitely prefer to concentrate on getting the man pages
accurate, and then as a second thing maybe worry about things like how
the options are presented.
---