man page needs better troff syntax

 affects /products/bzr
 importance low

I've done a quick review of the bzr.1 man output, and according to my
reading on troff its got some defects. Primarily we dont generate
typesetting metadata around options and paragraphs. e.g.
----
.SS "bzr version"

Options:
    \-\-help, \-h show help message

Show version of bzr.
.SS "bzr version\-info [LOCATION]"

Options:
    \-\-all include all possible information
    \-\-check\-clean check if tree is clean
    \-\-format ARG Select the output format
    \-\-help, \-h show help message
    \-\-include\-file\-revisions Include the last revision for each
file
    \-\-include\-history Include the revision\-history

Show version information about this tree.
.SS "bzr whoami [NAME]"
-----

should become

----
.SS "bzr version"
.PP
Options:
.RS
\-\-help, \-h show help message
.RE
.PP
Show version of bzr.
.SS "bzr version\-info [LOCATION]"
.PP
Options:
.RS
\-\-all include all possible information
\-\-check\-clean check if tree is clean
\-\-format ARG Select the output format
\-\-help, \-h show help message
\-\-include\-file\-revisions Include the last revision for each file
\-\-include\-history Include the revision\-history
.RE
.PP
Show version information about this tree.
.SS "bzr whoami [NAME]"
----

Now the
\-\-all include all possible information
also needs typesetting for the two column aspect. One way would be to
use .nf and .fi to prevent formatting of the options, another would be
to use tables. Using tabs isn't safe in the presence of long options.

-Rob

--
GPG key available at: <http://www.robertcollins.net/keys.txt>.