Re: [9fans] Capitalization in man pages.

[Lyndon Nerenberg <lyndon@orthanc.ca>]

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