From mboxrd@z Thu Jan 1 00:00:00 1970 Message-ID: <0efa86b8841cd02d62f592d615c7579d@terzarima.net> To: 9fans@cse.psu.edu Subject: Re: [9fans] Capitalization in man pages. From: Charles Forsyth Date: Tue, 6 Dec 2005 13:41:12 +0000 In-Reply-To: MIME-Version: 1.0 Content-Type: text/plain; charset="US-ASCII" Content-Transfer-Encoding: 7bit Topicbox-Message-UUID: ba302580-ead0-11e9-9d60-3106f5b1d025 >> 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.