docutils/docs/user/manpage.txt

   1 ==============================
   2  manpage writer for Docutils_
   3 ==============================
   4
   5 :Author: Engelbert Gruber
   6 :Contact: docutils-develop@lists.sourceforge.net
   7 :Revision: $Revision$
   8 :Date: $Date$
   9 :Copyright: This document has been placed in the public domain.
  10
  11 This writer explores the posibilities to generate man-pages from
  12 reStructuredText. Man pages are the way for Unix systems to provide
  13 help to the user. GNU does this with (TeX)info-pages.
  14
  15 .. contents::
  16
  17
  18 Module information
  19 ''''''''''''''''''
  20
  21 Unix man page belong into a numbered section, 1 is user commands, 8 contains
  22 administrator commands, the headlines of all manpages are collected into a
  23 database, queryable with the programm ``apropos``, therefore the headline
  24 should contain a short text describing into which group this command belongs.
  25
  26 These informations are collected from title, subtitle and the docinfo.
  27
  28 Also man pages have a defined set of sections, that are more or less
  29 mandatory, see References_.
  30
  31 man pages look like::
  32
  33    man(1)     Man Pager Utils     man(1)
  34
  35    NAME
  36        man - an interface to the on-line reference manuals
  37
  38    SYNOPSIS
  39        man [-c|-w|-tZT device] [-adhu7V] [-m system[,...]] [-L locale]
  40
  41 in roff formatting::
  42
  43      .TH man 1 "14 May 2001" "2.3.19" "Manual pager utils"
  44      .SH NAME
  45      man \- an interface to the on-line reference manuals
  46      .SH SYNOPSIS
  47      .\" The general command line
  48      .B man
  49      .RB [\| \-c \||\| \-w \||\| \-tZT
  50      .IR device \|]
  51
  52 This means we have
  53
  54 * a title "man"
  55 * a subtitle "an interface to the on-line reference manuals"
  56 * a manual section "1"
  57 * a manual group "Manual pager utils"
  58 * a date "14 May 2001"
  59 * a version "2.3.19"
  60
  61 References
  62 ''''''''''
  63
  64 man pages from section 7, ``man`` and ``man-pages``.
  65
  66 .. [LMHT] Linux Man Page Howto.
  67
  68 Conventions
  69 '''''''''''
  70
  71 * man pages have a special structure and organization. From the manpage
  72   to *man*::
  73
  74     The table below shows the section numbers of the manual followed  by  the
  75     types of pages they contain.
  76
  77     1   Executable programs or shell commands
  78     2   System calls (functions provided by the kernel)
  79     3   Library calls (functions within program libraries)
  80     4   Special files (usually found in /dev)
  81     5   File formats and conventions eg /etc/passwd
  82     6   Games
  83     7   Miscellaneous  (including  macro  packages and conven-
  84         tions), e.g. man(7), groff(7)
  85     8   System administration commands (usually only for root)
  86     9   Kernel routines [Non standard]
  87
  88     A manual page consists of several parts.
  89
  90     They  may  be  labelled  NAME,  SYNOPSIS,  DESCRIPTION,  OPTIONS,  FILES,
  91     SEE ALSO, BUGS, and AUTHOR.
  92
  93     The  following  conventions apply to the SYNOPSIS section and can be used
  94     as a guide in other sections.
  95
  96     bold text          type exactly as shown.
  97     italic text        replace with appropriate argument.
  98     [-abc]             any or all arguments within [ ] are optional.
  99     -a|-b              options delimited by | cannot be used together.
 100     argument ...       argument is repeatable.
 101     [expression] ...   entire expression within [ ] is repeatable.
 102
 103     The command or function illustration is a pattern that should  match  all
 104     possible  invocations.   In some cases it is advisable to illustrate sev-
 105     eral exclusive invocations as is shown in the SYNOPSIS  section  of  this
 106     manual page.
 107
 108 * new lines in general.
 109
 110   Consecutive blank lines are merged by the viewer but not on printouts.
 111   So one has to be cautious. This is most disturbing when printing
 112   postscript.
 113
 114   .. NOTE::
 115
 116     1. Roff requests only work when at line start.
 117     2. But consecutive blank lines are merged by the viewer but not on
 118        printouts.
 119
 120     So try the rule start new lines in ``visit_``-functions, but only if
 121     necessary. E.g. ``field-names`` are already on a new line because of
 122     docutils structure.
 123
 124 * Indentation, left margin:
 125
 126   - The writer includes two macros ``.INDENT`` and ``.UNINDENT`` that
 127     keep track of the indentation in roff-code, for line-blocks python
 128     keeps track of it. WHAT should be the preferred way ?
 129
 130     But standard macros like ``.PP`` might reset it.
 131
 132   - Why do ``.RE`` and ``.RS`` not work?
 133
 134   .. Note::
 135      Current indent is in register ``.i``.
 136
 137 * [LMHT]_ Filenames are always in italics, except in the SYNOPSIS section,
 138   use::
 139
 140     .I /usr/include/stdio.h
 141
 142   and::
 143
 144     .B #include <stdio.h>
 145
 146 * Tables are possible, via the external processor tbl, although one should
 147   avoid them.
 148
 149 Open issues
 150 '''''''''''
 151
 152 * How to typeset command/manpage names in text.
 153 * How to write long syntax lines.
 154 * Line ends around email or web addresses in texts.
 155   How to distinguish something is inline or not ?
 156
 157 * Images and equations are discouraged.
 158 * Lists in admonitions are not intended.
 159 * Encoding declaration ``'\" t -*- coding: ISO-8859-1 -*-``
 160   in first line.
 161
 162   BUT if UTF-8 is declared tables are no longer processed.
 163
 164 * Input and output encoding are problematic at least.
 165
 166 .. _Docutils: http://docutils.sourceforge.net/