Re: description writing guide
On Wed, Dec 04, 2002 at 07:19:38PM +0000, Scott James Remnant wrote:
> If you are writing text in something that uses variable width fonts, the
> program should know about English grammar and render the wider space
> itself on any whitespace. (LaTeX is about the only thing that gets it
> right though).
*roff also does, provided that you start each sentence on a new line (to
allow it to distinguish between full stops for abbreviations and full
stops at the end of sentences). Thus it's good style for man pages to be
written like this rather than wrapping the start of one sentence onto
the same line as the end of the last:
There are several common reasons why whatis parsing fails.
Sometimes authors of manual pages replace \(oq.SH NAME\(cq with
\(oq.SH MYPROGRAM\(cq, and then
.B mandb
cannot find the section from which to extract the information it needs.
Sometimes authors include a NAME section, but place free-form text there
rather than \(oqname \e\- description\(cq.
However, any syntax resembling the above should be accepted.
--
Colin Watson [cjwatson@flatline.org.uk]
Reply to: