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/ -- https://mail.python.org/mailman/listinfo/python-list
