Re: [9fans] Capitalization in man pages.

[Rob Pike <robpike@gmail.com>]

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