docutils/docs/user/manpage.txt

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