From mboxrd@z Thu Jan 1 00:00:00 1970 Mime-Version: 1.0 (Apple Message framework v746.2) In-Reply-To: <7359f0490512052301j592031dft96b46e860da7198d@mail.gmail.com> References: <7359f0490512051714m21e8b7ffrd1e60bab69d8edc4@mail.gmail.com> <8FBB88DB-680F-4180-ACCD-DD0E29626B99@orthanc.ca> <7359f0490512052301j592031dft96b46e860da7198d@mail.gmail.com> Content-Type: text/plain; charset=US-ASCII; delsp=yes; format=flowed Message-Id: Content-Transfer-Encoding: 7bit From: Lyndon Nerenberg Subject: Re: [9fans] Capitalization in man pages. Date: Tue, 6 Dec 2005 04:22:28 -0800 To: Fans of the OS Plan 9 from Bell Labs <9fans@cse.psu.edu> Topicbox-Message-UUID: b9e0dd0e-ead0-11e9-9d60-3106f5b1d025 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