[9fans] irc answers - man and memmove

[9fans] irc answers - man and memmove

[Russ Cox]

(Sorry, don't have email addresses for these people.)

sretzki   interesting, one of the biggest problems I have with
          plan9 is that functions in manpages are handled as
          normal words, instead of e.g. postfixing every function
          with ()
          but I guess that is just me and personal taste

fgb       ah, yes
          I think it's because the manuals are intended to be
          printed too

sretzki   Well, it is not that awfull, most times, it is clear.
          There is no such English word like "alloctree". Just
          that they are capitalized at the start of sentences,
          but you look at the prototype at the beginning of the
          manpage, anyway
          it becomes interesting if the function is a valid English
          word, like "respond" in 9p(2) :)

If you read the pages with man -P, which shows you the typeset
version, these names will be in italics, which should make them
easier for you to recognize as function names.  The manual is,
as fgb and man(1) point out, intended to be typeset.

equuelus  which file(s) do i need to include when i want to use
          memcpy in the kernel, tried #include "libc.h", but
          that didn't work. anyideas?

Use memmove instead, which has the same definition on all systems.
See memory(3):

     BUGS
          ANSI C does not require memcpy to handle overlapping source
          and destination; on Plan 9, it does, so memmove and memcpy
          behave identically.

Russ

Re: [9fans] irc answers - man and memmove

[Sascha Retzki]

On Mon, Dec 05, 2005 at 07:07:25AM -0500, Russ Cox wrote:
> If you read the pages with man -P, which shows you the typeset
> version, these names will be in italics, which should make them
> easier for you to recognize as function names.  The manual is,
> as fgb and man(1) point out, intended to be typeset.

Thanks! Thanks for your mailing 9fans (thus, caring enough to point
it out to all of us)


Sascha

> Russ
> 

Re: [9fans] irc answers - man and memmove

[Paul Lalonde]

On 5-Dec-05, at 4:07 AM, Russ Cox wrote:
> If you read the pages with man -P, which shows you the typeset
> version, these names will be in italics, which should make them
> easier for you to recognize as function names.  The manual is,
> as fgb and man(1) point out, intended to be typeset.

Actually, my biggest man page complaint is the capitalization of the  
symbols at the front of a sentence.  I usually B3 to find the  
particular function I care about, and it is frequently capitalized,  
breaking the search.

Paul

Re: [9fans] irc answers - man and memmove

[Rob Pike]

Sentences begin with capital letters.

-rob

On 12/5/05, Paul Lalonde <plalonde@telus.net> wrote:
>
> On 5-Dec-05, at 4:07 AM, Russ Cox wrote:
> > If you read the pages with man -P, which shows you the typeset
> > version, these names will be in italics, which should make them
> > easier for you to recognize as function names.  The manual is,
> > as fgb and man(1) point out, intended to be typeset.
>
> Actually, my biggest man page complaint is the capitalization of the
> symbols at the front of a sentence.  I usually B3 to find the
> particular function I care about, and it is frequently capitalized,
> breaking the search.
>
> Paul
>
>

Re: [9fans] irc answers - man and memmove

[Paul Lalonde]

I'm in complete agreement.  I just loathe the plumber hack to do case- 
insensitive first-letter in man pages.  I should just spend the 3  
minutes and do it.

Paul

On 5-Dec-05, at 5:14 PM, Rob Pike wrote:

> Sentences begin with capital letters.
>
> -rob
>
> On 12/5/05, Paul Lalonde <plalonde@telus.net> wrote:
>>
>> On 5-Dec-05, at 4:07 AM, Russ Cox wrote:
>>> If you read the pages with man -P, which shows you the typeset
>>> version, these names will be in italics, which should make them
>>> easier for you to recognize as function names.  The manual is,
>>> as fgb and man(1) point out, intended to be typeset.
>>
>> Actually, my biggest man page complaint is the capitalization of the
>> symbols at the front of a sentence.  I usually B3 to find the
>> particular function I care about, and it is frequently capitalized,
>> breaking the search.
>>
>> Paul
>>
>>

Re: [9fans] irc answers - man and memmove

[erik quanstrom]

they do? ☺

dispite my own disregard for the convention, i was about to reply that
i think that the software should conform to human standards and
not the other way around.

but rob beat me to it.

- erik

Rob Pike <robpike@gmail.com> writes

| 
| Sentences begin with capital letters.
| 
| -rob
| 
| On 12/5/05, Paul Lalonde <plalonde@telus.net> wrote:
| >
| > On 5-Dec-05, at 4:07 AM, Russ Cox wrote:
| > > If you read the pages with man -P, which shows you the typeset
| > > version, these names will be in italics, which should make them
| > > easier for you to recognize as function names.  The manual is,
| > > as fgb and man(1) point out, intended to be typeset.
| >
| > Actually, my biggest man page complaint is the capitalization of the
| > symbols at the front of a sentence.  I usually B3 to find the
| > particular function I care about, and it is frequently capitalized,
| > breaking the search.
| >
| > Paul
| >
| >

Re: [9fans] irc answers - man and memmove

[Russ Cox]

> I'm in complete agreement.  I just loathe the plumber hack to do case-
> insensitive first-letter in man pages.  I should just spend the 3
> minutes and do it.

It is not too hard to highlight all but the first letter.
Even easier if you type it in the tag, select it with b1,
and then b3 to search.

Russ

[9fans] Capitalization in man pages.

[Lyndon Nerenberg]

On Dec 5, 2005, at 5:14 PM, Rob Pike wrote:

> Sentences begin with capital letters.

But not all proper names do.

These are man pages, not novels.  I think consistency (accuracy,  
really) wins here.

--lyndon

Re: [9fans] Capitalization in man pages.

[Rob Pike]

They are English text and English text has rules.  Accuracy
and consistency counts for English, too.

The word 'the' is not capitlized unless it begins a sentence.
Why should any other word behave differently?  I know, because
programs are special. Well, they're not - at least within the
context of English text.

I spent most of my time for two years editing these pages
for publication.  To avoid the confusion that can be introduced
by capitalizing a magic word, where possible I rewrote the
sentence to avoid the problem.  Not
    Qsort sorts data
but
    The qsort function sorts data

If you see many instances that sow such confusion, either
I missed them the first time or, more likely, they've been
edited since by someone less focused.  Fix the text.

-rob


On 12/5/05, Lyndon Nerenberg <lyndon@orthanc.ca> wrote:
>
> On Dec 5, 2005, at 5:14 PM, Rob Pike wrote:
>
> > Sentences begin with capital letters.
>
> But not all proper names do.
>
> These are man pages, not novels.  I think consistency (accuracy,
> really) wins here.
>
> --lyndon
>

Re: [9fans] Capitalization in man pages.

[Charles Forsyth]

following the rules of English text in manual pages
was followed reasonably consistently in later versions
of Unix, and in all the years i've worked with any
of the systems, i cannot recall an instance where i
was stumped, and certainly was never so perplexed that
i couldn't invoke the command or write the code
to call the function.   (the content of manual pages
in some other Unix-like systems is quite another matter,
but i refer only to Unix and its relatives.)

as with the `obfuscated X' contests (where X is a variable, but obviously
includes the window system), no doubt one can construct
a manual page that provokes a mixture of humour and head-scratching,
but that's art or artifice not documentation.

Re: [9fans] Capitalization in man pages.

[Lyndon Nerenberg]

On Dec 5, 2005, at 11:01 PM, Rob Pike wrote:

> Fix the text.

Okay, Mr. Grumpy :-)

The nice thing about standards is there are so many to choose from.

So which of the 15 style manuals sitting on my shelf should I follow  
for the rewrite :-)

My philosophy is that man pages describe code.  I don't capitalize  
function names, etc., in my code, and likewise in my man pages. Ymmv.

--lyndon

P.S.  I think "Nasa" is an abomination as well, but who am I to fight  
the New York Times?

Re: [9fans] Capitalization in man pages.

[Lyndon Nerenberg]

On Dec 5, 2005, at 11:01 PM, Rob Pike wrote:

> To avoid the confusion that can be introduced
> by capitalizing a magic word, where possible I rewrote the
> sentence to avoid the problem.

With the nice side effect of making the pages more readable in  
general.  Maintaining a balance between tech-geek and understandable  
descriptions of functionality in man pages is an art.  There aren't  
many people who can do it, let alone do it well.  It's a dilemma  
Shakespeare would have appreciated, I think.  (Oh lord, do I see a  
Monty Python skit looming?)

--lyndon

Re: [9fans] Capitalization in man pages.

[Charles Forsyth]

> My philosophy is that man pages describe code.  I don't capitalize  

Code??! well, there's a thought for us all.

Re: [9fans] Capitalization in man pages.

[Lucio De Re]

> Maintaining a balance between tech-geek and understandable  
> descriptions of functionality in man pages is an art.

Poetry, in fact.  :-)

++L

Re: [9fans] Capitalization in man pages.

[Lyndon Nerenberg]

On Dec 6, 2005, at 3:17 AM, Charles Forsyth wrote:

> Code??! well, there's a thought for us all.

Writing code is easy.  Writing the man page for it is the part that  
always gives me ulcers.  And what pisses me off the most is that  
nobody else in the company even gives a f*** about the quality of the  
documentation.  The number of times I've tried to explain the  
difference between a man page and a user manual, well ...

I guess what bugs me about this whole topic is that the man pages I  
ship with my code are the visible representation of my work,  
therefore I put a lot of effort into writing something that *I* would  
want to read, as the end user.  These days, nobody seems to  
understand why that's important ...

--lyndon (frustrated writer?)

Re: [9fans] Capitalization in man pages.

[Lyndon Nerenberg]

On Dec 5, 2005, at 11:01 PM, Rob Pike wrote:

> If you see many instances that sow such confusion, either
> I missed them the first time or, more likely, they've been
> edited since by someone less focused.

Or perhaps the underlying conflict is that between the grammars of C  
and English.  C's grammar is concise, and does not suffer ambiguity  
(ANSI notwithstanding), whereas English thrives on ambiguity.  For man 
(6) authors this is the pit of dispair.

I confess to being a fan of the BSD mdoc macros.  They recommend a  
writing style that strikes a reasonable balance between the goals of  
prose vs. precise.  But most importantly, they try to ensure  
consistency throughout the documentation set.  When it comes to  
laying out documentation -- especially reference documentation --  
consistency of style is critical to making it easy for the reader to  
find what they need.  The correct use of layout and typefaces will  
quickly draw the reader to the information they are scanning for.   
Using an offsetting typeface to highlight (only) function names will  
immediately draw the eye to that information; mixing case just stalls  
the rapid scanning process, as the brain has to pause to assimilate  
the "almost" pattern match in the context of the search.  And it's  
this visual scanning process that concerns me.  Mixed case for grep  
is easily solved with -i.

--lyndon

Re: [9fans] Capitalization in man pages.

[Charles Forsyth]

> But most importantly, they try to ensure  
> consistency throughout the documentation set.

so does Plan 9; it just doesn't use your rules.

Re: [9fans] Capitalization in man pages.

[Lyndon Nerenberg]

On Dec 6, 2005, at 4:32 AM, Charles Forsyth wrote:

> so does Plan 9; it just doesn't use your rules.

So the discussion of different ways of doing things is out of  
bounds?  Isn't that what moved us beyond UNIX?  Relax, folks.  I'm  
just trying to exchange some ideas here.

Re: [9fans] Capitalization in man pages.

[erik quanstrom]

thanks for the effort.

the plan 9 (and antecedent unix) papers and man pages really made the systems'
influence great.

- erik

Rob Pike <robpike@gmail.com> writes

| I spent most of my time for two years editing these pages
| for publication.  To avoid the confusion that can be introduced
| by capitalizing a magic word, where possible I rewrote the
| sentence to avoid the problem.  Not
|     Qsort sorts data
| but
|     The qsort function sorts data

Re: [9fans] Capitalization in man pages.

[Lyndon Nerenberg]

On Dec 6, 2005, at 4:32 AM, Charles Forsyth wrote:

>> But most importantly, they try to ensure
>> consistency throughout the documentation set.
>
> so does Plan 9; it just doesn't use your rules.

I'm curious about this comment.  man(6) describes the macros it makes  
available, but it says nothing about how they should be used in the  
context of writing the man page itself.  There is no mention  
whatsoever of style or usage.  (USG derived UNIXen suffered this  
malady as well, to varying degrees.)

So how is an author to know how to write something that is congruent  
with the current style?  They can read existing man pages and try to  
glean from them, but inevitably errors will creep in.  And those  
errors will become input to the next generation of authors, and so it  
goes.

Wasn't it Steve Johnson who did the original sweep through the UNIX  
man pages, editing out inconsistent usage and rationalizing the  
layout?  In the 1970s?

--lyndon

P.S.  And no, I am not in any way pissing on Rob's work!

Re: [9fans] Capitalization in man pages.

[Charles Forsyth]

>> so does Plan 9; it just doesn't use your rules.
> 
> I'm curious about this comment.  man(6) describes the macros it makes  
> available, but it says nothing about how they should be used in the  
> context of writing the man page itself.  There is no mention  
> whatsoever of style or usage.  (USG derived UNIXen suffered this  
> malady as well, to varying degrees.)

sorry, i meant only that the pages themselves are reasonably consistent in their style
and usually in the way they use man(6), though that's less visible.
you're quite right, though, that neither is codified.
i probably just misunderstood the following, or read it too quickly,
and thought you were implying there was no (real) consistency.

>I confess to being a fan of the BSD mdoc macros.  They recommend a  
>writing style that strikes a reasonable balance between the goals of  
>prose vs. precise.  But most importantly, they try to ensure  
>consistency throughout the documentation set.  When it comes to  
>laying out documentation -- especially reference documentation --  
>consistency of style is critical to making it easy for the reader to  
>find what they need.  The correct use of layout and typeface ...

i took it to mean that the 9 man pages didn't do (enough) of that;
i was asserting the contrary, but as i've just said, i was referring to the
style on the page, not to the underlying macro usage or whether
guidance or templates were provided anywhere.

i did look at mdoc(7) and mdoc.samples(7)
but although the latter provided a useful tutorial on using mdoc,
it didn't seem to touch significantly on writing style.

Re: [9fans] Capitalization in man pages.

[Lyndon Nerenberg]

On Dec 6, 2005, at 5:41 AM, Charles Forsyth wrote:

> i did look at mdoc(7) and mdoc.samples(7)
> but although the latter provided a useful tutorial on using mdoc,
> it didn't seem to touch significantly on writing style.

They do avoid talking about writing style.  What I was getting at was  
the macros themselves try to enforce a consistent design (i.e.  
consistent use of unique typefaces to highlight function names vs.  
parameters vs. manifest constants, etc.), thus enforcing the visual  
cues I mentioned before.  (And they even work to a limited extent  
with nroffed pages, although most of what I'm alluding to is based on  
the typeset pages.)  But the unwritten style guide for BSD man pages  
says function names (and almost everything else) are case preserved.

--lyndon

Re: [9fans] Capitalization in man pages.

[John Stalker]

> the typeset pages.)  But the unwritten style guide for BSD man pages  
> says function names (and almost everything else) are case preserved.
> 
> --lyndon

Are you sure?  I just looked at Rob's example, qsort(3), on my FreeBSD
system.  It mostly follows his usage, but there was

  Mergesort() is optimized for data with pre-existing order

I think FreeBSD generally follows the traditional UNIX usage in this
regard.  The traditional usage worked quite well when identifiers
were all short and lower case.  The problems begin when people name
their functions things like i2d_PKCS8PrivateKey_nid_bio. 


--
John Stalker
University of Dublin, Trinity College
School of Mathematics

Re: [9fans] Capitalization in man pages.

[Brantley Coile]

> thanks for the effort.

Here, here!

> 
> the plan 9 (and antecedent unix) papers and man pages really made the systems'
> influence great.

What Plan 9 needed was for Brian Kernighan to be 15 years younger.

 bc

Re: [9fans] Capitalization in man pages.

[jmk]

Seems to me you could satisfy both your desire for consistency
and that of being a frustrated writer by writing the man page that
details how to write a man page in the accepted Plan 9 style.

--jim

On Tue Dec  6 08:03:30 EST 2005, lyndon@orthanc.ca wrote:
> 
> On Dec 6, 2005, at 4:32 AM, Charles Forsyth wrote:
> 
> >> But most importantly, they try to ensure
> >> consistency throughout the documentation set.
> >
> > so does Plan 9; it just doesn't use your rules.
> 
> I'm curious about this comment.  man(6) describes the macros it makes  
> available, but it says nothing about how they should be used in the  
> context of writing the man page itself.  There is no mention  
> whatsoever of style or usage.  (USG derived UNIXen suffered this  
> malady as well, to varying degrees.)
> 
> So how is an author to know how to write something that is congruent  
> with the current style?  They can read existing man pages and try to  
> glean from them, but inevitably errors will creep in.  And those  
> errors will become input to the next generation of authors, and so it  
> goes.
> 
> Wasn't it Steve Johnson who did the original sweep through the UNIX  
> man pages, editing out inconsistent usage and rationalizing the  
> layout?  In the 1970s?
> 
> --lyndon
> 
> P.S.  And no, I am not in any way pissing on Rob's work!

Re: [9fans] Capitalization in man pages.

[Charles Forsyth]

>> the typeset pages.)  But the unwritten style guide for BSD man pages  
>> says function names (and almost everything else) are case preserved.
>> 
>> --lyndon
> 
> Are you sure?  I just looked at Rob's example, qsort(3), on my FreeBSD
> system.  It mostly follows his usage, but there was
> 
>   Mergesort() is optimized for data with pre-existing order

actually, the amusing thing for me is that most pages in plan 9's section 2
use the latter style: Open opens, Create creates, Lalloc allocates a Layer,
Read reads, Write writes, Seek sets an offset, and so on.  Qsort sorts an array.
few pages use `the function ...', although some do when it makes sense.
outside section 2, Cat reads each file, Clock draws a clock, ...

one can see why, when there are many functions.
with the `Lalloc allocates' style, the function name is often the start
of a paragraph describing the function.  when several are
discussed in one paragraph, and a function name is just the start of a line not a paragraph, the
capital helps it stand out from the preceding sentence.

of course, i don't write my own throwaway e-mail following any of those conventions!
i'm anyway currently stuck in a grim world of
public abstract SocketChannel extends java.nio.channels.spi.AbstractSelectableChannel
implements ByteChannel, GatheringByteChannel, ScatteringByteChannel
where clearly no names are used lightly; and there are many.

Re: [9fans] Capitalization in man pages.

[Rob Pike]

My memory is clearly faulty, but the point remains that if the writing
is inadequate, rewrite.

-rob

On 12/6/05, Charles Forsyth <forsyth@terzarima.net> wrote:
> >> the typeset pages.)  But the unwritten style guide for BSD man pages
> >> says function names (and almost everything else) are case preserved.
> >>
> >> --lyndon
> >
> > Are you sure?  I just looked at Rob's example, qsort(3), on my FreeBSD
> > system.  It mostly follows his usage, but there was
> >
> >   Mergesort() is optimized for data with pre-existing order
>
> actually, the amusing thing for me is that most pages in plan 9's section 2
> use the latter style: Open opens, Create creates, Lalloc allocates a Layer,
> Read reads, Write writes, Seek sets an offset, and so on.  Qsort sorts an array.
> few pages use `the function ...', although some do when it makes sense.
> outside section 2, Cat reads each file, Clock draws a clock, ...
>
> one can see why, when there are many functions.
> with the `Lalloc allocates' style, the function name is often the start
> of a paragraph describing the function.  when several are
> discussed in one paragraph, and a function name is just the start of a line not a paragraph, the
> capital helps it stand out from the preceding sentence.
>
> of course, i don't write my own throwaway e-mail following any of those conventions!
> i'm anyway currently stuck in a grim world of
> public abstract SocketChannel extends java.nio.channels.spi.AbstractSelectableChannel
> implements ByteChannel, GatheringByteChannel, ScatteringByteChannel
> where clearly no names are used lightly; and there are many.
>
>

Re: [9fans] Capitalization in man pages.

[geoff]

I could distribute Henry Spencer's paper on how to write a manual
page, touched up for Plan 9, if people really feel the need for
guidance.

Re: [9fans] Capitalization in man pages.

[Francisco J Ballesteros]

I´d like to read that.

On 12/7/05, geoff@collyer.net <geoff@collyer.net> wrote:
> I could distribute Henry Spencer's paper on how to write a manual
> page, touched up for Plan 9, if people really feel the need for
> guidance.
>

Re: [9fans] Capitalization in man pages.

[Steve Simon]

> I could distribute Henry Spencer's paper on how to write a manual
> page, touched up for Plan 9, if people really feel the need for
> guidance.

My poor manual pages are notorious, I'm
sure I ought to read it.

-Steve

Re: [9fans] Capitalization in man pages.

[Jeff Sickel]

On Dec 6, 2005, at 12:11 PM, Charles Forsyth wrote:

> i'm anyway currently stuck in a grim world of
> public abstract SocketChannel extends  
> java.nio.channels.spi.AbstractSelectableChannel
> implements ByteChannel, GatheringByteChannel, ScatteringByteChannel
> where clearly no names are used lightly; and there are many.


I'd say "run away!", but I'm sure there's a reason to the insanity of  
all the Java class hierarchies.  That said, I'm still all for  
following the mantra: deleted code is debugged code.  And there are  
is a lot of source code in the above space that deserves to be  
debugged through deletion.

Though JStyx opens up the concepts from Plan 9 and Inferno into the  
Java space, there's still a lot left to be desired.  So much so that  
from the seat I'm sitting in, it's really difficult justifying going  
down that road when using Inferno or plan9port would at least keep  
some of the architecture a little more sane.

Granted, it would be nice to see Inferno piggy back on the JDBC layer  
since ODBC has even more constraints these days (hard to believe).   
But I'd still like to see a new Inferno release and documentation,  
properly capitalized of course, before more Java classes I'll never  
get the opportunity to use see the light of day.

jas

Re: [9fans] irc answers - man and memmove

[Gorka guardiola]

If this isnt in the Faq it should be. It comes now and then to the mail list...

On 12/6/05, Russ Cox <rsc@swtch.com> wrote:
> > I'm in complete agreement.  I just loathe the plumber hack to do case-
> > insensitive first-letter in man pages.  I should just spend the 3
> > minutes and do it.
>
> It is not too hard to highlight all but the first letter.
> Even easier if you type it in the tag, select it with b1,
> and then b3 to search.
>
> Russ
>


--
- curiosity sKilled the cat

Re: [9fans] irc answers - man and memmove

[Lucio De Re]

> If this isnt in the Faq it should be. It comes now and then to the mail list...

We've forgotten about the "hint of the day" already?

++L

Re: [9fans] Capitalization in man pages.

[Lyndon Nerenberg]

On Dec 6, 2005, at 7:57 AM, jmk@plan9.bell-labs.com wrote:

> Seems to me you could satisfy both your desire for consistency
> and that of being a frustrated writer by writing the man page that
> details how to write a man page in the accepted Plan 9 style.

Fair enough.  I'll try to find some time over the Christmas holidays  
to work on that.

--lyndon

Re: [9fans] Capitalization in man pages.

[Lyndon Nerenberg]

On Dec 6, 2005, at 10:31 AM, Rob Pike wrote:

> My memory is clearly faulty, but the point remains that if the writing
> is inadequate, rewrite.

If things were rewritten to mdoc, would that be accepted?  As you  
say, it's a hell of a lot of work.  I will do it, but not if it's  
going to be thrown out for NIH.

--lyndon

Re: [9fans] Capitalization in man pages.

[Russ Cox]

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.

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.

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.

Russ

Re: [9fans] Capitalization in man pages.

[Uriel]

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.
---