[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

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: