[Summary] Re: How to test a manpage? ‘nroff -man | less’ does not display like ‘man’.

[Charles Plessy <plessy@debian.org>]

Many thanks to everybody for their interesting answers. Here is a short
summary, and examples for a manpage called manpage.1.gz, in the current
directory.

Have a nice week-end,

-- Charles


How to test a local manpage.

Some manual pages are using helpers, usually ‘tbl’, ‘eqn’ or ‘pic’. In these
cases, a simple command like ‘nroff -man’ will not be enough to process them.
Preprocessors can be invoked through command-line options, like ‘-t’ for ‘tbl‘.
A list of these options can be found in the groff(1) manpage, and groffer(1)
can autodetect them. Alternatively, they can be ran separately as filters, like
in the following example:

  zcat manpage.1.gz | tbl | nroff -man > manpage.txt

‘man’ can also be used to open a manpage that is in the current directory, by
using the -l (--local) option, or by indicating its path:

  man -l manpage.1.gz
  man ./manpage.1.gz

In Debian, the manual pages are using the UTF-8 encoding. To visualise a local
manpage with man or groff the same way as it would appear to the users once it
is installed in /usr/share/man/, the encoding has to be specified:

zcat manpage.1 | groff -T utf8 -man > manpage.txt
man -E UTF-8 -l manpage.1.gz > manpage.txt

When inspecting a manpage, it may be better to assume a 80-columns terminal,
by setting the environment variable MANWIDTH. Using the C or the en_US.UTF-8
locales also gets the environment closer to a default Debian installation.

In full, a command to test a manpage before including it in a Debian package
looks like this:

  # Displays the warnings
  LANG=en_US.UTF-8 MANWIDTH=80 man --warnings -E UTF-8 -l manpage.1.gz > /dev/null

  # Displays the manpage with ‘less’.
  LANG=C MANWIDTH=80 man --warning -l manpage.1.gz | less