sandbox/manpage-writer/rst2man.txt

   1 =========
   2  rst2man
   3 =========
   4
   5 ---------------------------------------------
   6 generate unix manpages from reStructured text
   7 ---------------------------------------------
   8
   9 :Author: grubert@users.sourceforge.net
  10 :Date:   2006-10-23
  11 :Copyright: public domain
  12 :Version: 0.1
  13 :Manual section: 1
  14 :Manual group: text processing
  15
  16 .. TODO: authors and author with name <email>
  17
  18 SYNOPSIS
  19 ========
  20
  21   rst2man.py inputfile outputfile
  22
  23 DESCRIPTION
  24 ===========
  25
  26 rst2man transforms a reStructured text document into a unix man page.
  27
  28 In theory any valid reStructured text document should be processable,
  29 in reality this is
  30
  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.
  35
  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.
  41
  42   These informations are collected from title, subtitle and the
  43   docinfo, see this document as an example.
  44
  45 OPTIONS
  46 =======
  47
  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.
  51
  52 And a lot more standard docutils options.
  53
  54 PROBLEMS
  55 ========
  56
  57 1. linux man page howto advises to use the man macro package,
  58    UCB uses the newer doc macros.
  59
  60 SEE ALSO
  61 ========
  62
  63 * `docutils <http://docutils.sourceforge.net>`__
  64 * `linux man page howto <http://tldp.org/HOWTO/Man-Page/>`__
  65 * ``man man`` and ``man 7 man``
  66
  67 BUGS
  68 ====
  69
  70 * Format options are included as they are required, only the simplest
  71   options are supported, and no complex things should be used in man pages.
  72 * tables:
  73
  74   - no header allowed
  75   - always have a border
  76   - cell alignment is always top/left.
  77
  78 * images are not supported.
  79
  80 Discussion is still open.
  81
  82