Re: Writing manpages

[Ben Finney <ben+debian@benfinney.id.au>]

Rogério Brito <rbrito@ime.usp.br> writes:

> OK, since the project strongly advises for the availability of
> manpages (and I love manpages), comes the question: what do you people
> use to type manpages?

Type the page as a reStructuredText document, then render it to a
manpage with ‘rst2man’ <URL:http://packages.debian.org/rst2man>.

It's still a little rough, but the developer is actively seeking
improvements. The writer (the Docutils plug=in that renders reST to
*roff) is to be included in Docutils core in an upcoming release.

> The best so far that I found seems to be Perl's pod format. At least,
> the markup doesn't pollute my view.

I find reST to be the most sensible plain-text markup format by far
<URL:http://docutils.sourceforge.net/rst.html> with good HTML and PDF
rendering available (among other output renderings). I write new
documents in reST wherever possible. That's why I decided to package the
manpage writer for it :-)

-- 
 \        “Ubi dubium, ibi libertas.” (“Where there is doubt, there is |
  `\                                                        freedom.”) |
_o__)                                                                  |
Ben Finney