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