manpage writing [rst, asciidoc, pod] was [Re: What should Python apps do when asked to show help?]

[Martin A. Brown]

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/