The man-page sources use single quotes to quote text. However, this can be
problematic in man-pages because if a single quote appears at the beginning of a
line the following word is interpreted by troff as a macro. For example, this
paragraph in mu-easy.7:
What if we want to see some of the body of the message? You can get a 'summary'
of the first lines of the message using the \fI\-\-summary\-len\fP option, which will
'summarize' the first \fIn\fP lines of the message:
elicits this warning:
$ man --warnings obj-x86_64-linux-gnu/man/mu-easy.7 >/dev/null
troff:<standard input>:166: warning: macro 'summarize'' not defined
and gets truncated:
What if we want to see some of the body of the message? You can get a
'summary' of the first lines of the message using the --summary-len op‐
tion, which will
One could adjust the line-wrapping to move the quoted text away from the
beginning of the line, but that is fragile. Another possibility would be to use
the troff escape-sequences for open and close quotes (`\(oq` and `\(cq`
respectively), but ox-man is being used precisely to avoid having to handle
troff directly. Instead use back-ticks for left quotes. Thus:
What if we want to see some of the body of the message? You can get a `summary'
of the first lines of the message using the \fI\-\-summary\-len\fP option, which will
`summarize' the first \fIn\fP lines of the message:
which is rendered correctly:
What if we want to see some of the body of the message? You can get a
`summary' of the first lines of the message using the --summary-len op-
tion, which will `summarize' the first n lines of the message:
Signed-off-by: Jeremy Sowden <azazel@debian.org>
The command names are formatted inconsistently, e.g.:
* NAME
~mu add~ - add one or more messages to the database
versus:
* NAME
*mu cfind* is the *mu* command to find contacts in the *mu* database and export them
versus:
* NAME
mu server - the mu backend for the mu4e e-mail client
and the format, with a space between "mu" and the subcommand, is not compatible
with mandb(8). Use formatting which is consistent and replace the spaces with
hyphens.
Signed-off-by: Jeremy Sowden <azazel@debian.org>
Generate the manpages from org-documents which makes it a bit easier to
keep them update to date since I find org-syntax easier than troff, and
we can use include files.
Dirk-Jan C. Binnema
Ulrich Ölmann
Jeremy Sowden