5 ---------------------------------------------
6 generate unix manpages from reStructured text
7 ---------------------------------------------
9 :Author: grubert@users.sourceforge.net
11 :Copyright: public domain
14 :Manual group: text processing
16 .. TODO: authors and author with name <email>
21 rst2man.py inputfile outputfile
26 rst2man transforms a reStructured text document into a unix man page.
28 In theory any valid reStructured text document should be processable,
31 * a goal, that is not met yet
32 * a goal that might never be met, because only few constructs are
33 used in man pages *and* because the common text file does not adhere
34 to man page requirements.
36 For example a unix man page belongs into a numbered section, 1 is
37 user commands, 8 contains administrator commands and the headlines
38 of all manpages are collected into a database, queryable with the
39 programm ``apropos``, therefore the headline should contain a short
40 text describing into which group this command belongs.
42 These informations are collected from title, subtitle and the
43 docinfo, see this document as an example.
48 --config=<file> Read configuration settings from <file>, if it exists.
49 --version, -V Show this program's version number and exit.
50 --help, -h Show this help message and exit.
52 And a lot more standard docutils options.
57 1. linux man page howto advises to use the man macro package,
58 UCB uses the newer doc macros.
63 `docutils <http://docutils.sourceforge.net>`__
64 `linux man page howto <http://tldp.org/HOWTO/Man-Page/>`__
66 and ``man man`` ``man 7 man ``
71 * Format options are included as they are required, only the simplest
72 options are supported, and no complex things should be used in man pages.
76 - always have a border
77 - cell alignment is always top/left.
79 * images are not supported.
81 Discussion is still open.