From mboxrd@z Thu Jan  1 00:00:00 1970
Message-ID: <7359f0490512061031l37438297s18782869396d35e6@mail.gmail.com>
Date: Tue,  6 Dec 2005 10:31:28 -0800
From: Rob Pike <robpike@gmail.com>
To: Fans of the OS Plan 9 from Bell Labs <9fans@cse.psu.edu>
Subject: Re: [9fans] Capitalization in man pages.
In-Reply-To: <91a834f68df7b1af7de479b2062c27d7@terzarima.net>
MIME-Version: 1.0
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable
Content-Disposition: inline
References: <200512061430.aa89515@salmon.maths.tcd.ie>
	<91a834f68df7b1af7de479b2062c27d7@terzarima.net>
Topicbox-Message-UUID: ba823ea6-ead0-11e9-9d60-3106f5b1d025

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 Laye=
r,
> 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 li=
ne 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 c=
onventions!
> i'm anyway currently stuck in a grim world of
> public abstract SocketChannel extends java.nio.channels.spi.AbstractSelec=
tableChannel
> implements ByteChannel, GatheringByteChannel, ScatteringByteChannel
> where clearly no names are used lightly; and there are many.
>
>