manpage writing [rst, asciidoc, pod] was [Re: What should Python apps do when asked to show help?]
Martin A. Brown
martin at linux-ip.net
Fri Apr 29 09:32:54 EDT 2016
Hello,
>What is a good place where I can find out more about writing
>manpage?
I don't know of a single place where manpage authorship is
particularly documented. This seems to be one of the common target
links. In addition to introducing the breakdown of manpages by
type (section) and providing some suggestions for content, it
introduces the *roff markup:
http://www.schweikhardt.net/man_page_howto.html
It's been many years since I have written that stuff directly. I
prefer one of the lightweight, general documentation or markup
languages. So, below, I'll mention and give examples for creating
manpages from reStructuredtext, AsciiDoc and Plain Old
Documentation.
With the reStructuredText format [0] [1], you can convert an .rst
file to a manpage using two different document processors; you can
use sphinx-build from the sphinx-project [2] or rst2man from the
docutils project. The outputs are largely the same (as far as I
can tell).
There's also the AsciiDoc [3] format, which is a near to text and
reads like text, but has a clear structure. With the tooling
(written in Python), you can produce docbook, latex, html and a
bunch of other output formats. Oh, and manpages [4], too. There is
a tool called 'asciidoc' which processes AsciiDoc formats into a
variety of backend formats. The 'a2x' tool converts AsciiDoc
sources into some other (x) desired output.
If you don't like .rst or AsciiDoc, there's also the Plain Old
Documentation (POD) format. This is the oldest tool (of which I'm
aware) which other than the direct *roff processing tools. You run
'pod2man' (written in Perl) on your .pod file. POD is another dead
simple documentation language, supported by the pod2man [5] tool.
For more on the format, read also 'man 1 perlpod'.
sphinx-build: the sphinx documentation system is geared for
handling project-scoped documentation and provides many additional
features to reStructuredText. It can produce all kinds of output
formats, HTML single-page, help, multipage, texinfo, latex, text,
epub and ....oh, yeah, manpages. It's a rich set of tools.
If you wish to use sphinx, I can give you an example .rst file [6]
which I recently wrote and the following instructions for how to
process this with sphinx. When processing docs with sphinx, a
'conf.py' file is required. It can be generated with an ancillary
tool from the sphinx suite:
I know that I always find an example helpful. So, here are some
examples to help you launch.
mkdir sampledir && cd sampledir
sphinx-quickstart # -- and answer a bunch of questions
# -- examine conf.py and adjust to your heart's content
# confirm that master_doc is your single document for a manpage
# confirm that there's an entry for your document in man_pages
sphinx-build -b man -d _build/doctrees . _build/man
# -- or grab the files from my recent project [6] and try yourself
rst2man: even more simply, if you don't need the kitchen sink...
wget https://gitlab.com/pdftools/pdfposter/raw/develop/pdfposter.rst
rst2man < pdfposter.rst > pdfposter.1
# -- will complain about this, but still produces a manpage
# <stdin>:10: (ERROR/3) Undefined substitution referenced: "VERSION".
man ./pdfposter.1
asciidoc (a randomly selected example asciidoc file [7]):
wget https://raw.githubusercontent.com/DavidGamba/grepp/master/grepp.adoc
a2x -f manpage grepp.adoc
man ./grepp.1
perlpod:
wget https://api.metacpan.org/source/RJBS/perl-5.18.1/pod/perlrun.pod
pod2man --section 1 < perlrun.pod > perlrun.1
man ./perlrun.1
I know there are other tools for generating manpages; the
original *roff tools, visual manpage editors, DocBook,
help2man, manpage generators from argparse.ArgumentParser
instances,
And, of course, make sure to use version control for your
documentation. These git manpages may be helpful for the
uninitiated (joke, joke):
https://git-man-page-generator.lokaltog.net/ # -- humour!
Good luck,
-Martin
[0] http://docutils.sourceforge.net/docs/user/rst/quickref.html
[1] http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
[2] http://www.sphinx-doc.org/en/stable/rest.html
[3] http://www.methods.co.nz/asciidoc/
[4] http://www.methods.co.nz/asciidoc/chunked/ch24.html
[5] http://perldoc.perl.org/pod2man.html
[6] https://raw.githubusercontent.com/tLDP/python-tldp/master/docs/ldptool-man.rst
[7] https://raw.githubusercontent.com/DavidGamba/grepp/master/grepp.adoc
--
Martin A. Brown
http://linux-ip.net/
More information about the Python-list
mailing list