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 generates man pages from reStructuredText.  Man pages (short
  14 for "manual pages") are the way Unix systems have provided reference
  15 material to the user on demand, at the shell prompt or in printed and
  16 bound manuals, since 1971.  Some GNU projects offer a similar resource
  17 with the Texinfo system.
  18
  19 Man pages are usually formatted with a typesetting language and program
  20 called ``troff``.  *man* is a macro package for ``troff``.  OpenBSD,
  21 NetBSD, and some GNU/Linux distributions use an alternative program,
  22 ``mandoc``, that does not support any typesetting features that cannot
  23 be exercised in a terminal emulator, but supports enough *man* and
  24 ``troff`` syntax that it can meet many users' needs.  This writer
  25 produces a dialect that is supported by both programs.
  26
  27 Historically, the program for formatting on terminals is called
  28 ``nroff``.  When details of the output device are not important, we can
  29 refer to the language and its system as *roff*.
  30
  31
  32 .. contents::
  33
  34
  35 Module information
  36 ''''''''''''''''''
  37
  38 Man pages are organized into numbered sections.  A system's *intro*\(1)
  39 or *man*\(1) page lists them.  For example, section 1 documents
  40 user commands, and section 3 presents programming library functions.
  41 You will find a "printf" page in both sections; the notations
  42 *printf*\(1) and *printf*\(3) distinguish them.
  43
  44 A man page can discuss several topics; for example, the *gzip*\(1) page
  45 documents the ``gzip``, ``gunzip``, and ``zcat`` commands.  A man page's
  46 topic list is followed by a summary description containing key words
  47 that enable the page to located quickly with the ``apropos`` command.
  48
  49 A rST document's title becomes the man page's identifier, and the
  50 subtitle its summary description.  The title and docinfo populate the
  51 the man page's header and footer.
  52
  53 Each man page is organized by a standardized set of section headings;
  54 see References_.  Use additional section headings at your discretion
  55 only if the standard set does not serve.  Man pages support one level of
  56 subsection headings to further organize a section heading's material.
  57
  58 The beginning of a formatted man page might look like this::
  59
  60     man(1)                   Manual pager utils                   man(1)
  61
  62     NAME
  63          man - an interface to the system reference manuals
  64
  65     SYNOPSIS
  66          man [-c|-w|-tZT device] [-adhu7V] [-m system[,...]] [-L locale]
  67
  68 It would have a page footer with further information::
  69
  70     noman 1.2.3                  2021‐02‐08                       man(1)
  71
  72 It could be produced by the following *roff* input.
  73
  74 .. code:: man
  75
  76      .TH man 1 2021-02-08 "noman 1.2.3" "Manual pager utils"
  77      .SH NAME
  78      man \- an interface to the system reference manuals
  79      .SH SYNOPSIS
  80      .B man
  81      .RB [ \-c | \-w | \-tZT
  82      .IR device ]
  83
  84 We can write rST to produce the foregoing.
  85
  86 .. code:: rst
  87
  88   =====
  89    man
  90   =====
  91
  92   --------------------------------------------
  93   an interface to the system reference manuals
  94   --------------------------------------------
  95
  96   :Version: noman 1.2.3
  97   :Date: 2021-02-08
  98   :Manual section: 1
  99   :Manual group: Manual pager utils
 100
 101   SYNOPSIS
 102   ========
 103
 104   ``man`` ``[-c|-w|-tZT device] [-adhu7V] [-m system[,...]] [-L locale]``
 105
 106 The *man-db* project's own *man* page, which may be installed as
 107 *man*\(1) or *gman*\(1), explains the sectional organization of the
 108 manuals (in both senses).
 109
 110 References
 111 ''''''''''
 112
 113 Consult man pages from section 7: *man*, *man-pages*, *groff_man* and
 114 *groff_man_style*.
 115
 116 .. [LMHT] `Linux Man Page Howto <https://tldp.org/HOWTO/Man-Page/>`__.
 117
 118 Conventions
 119 '''''''''''
 120
 121 * Newlines, line breaks, and sentences
 122
 123   One should try to comply with the `troff line break rules`__ after
 124   ``.``, ``?``, and ``!`` punctuation signs in the rST source.  Use a
 125   new line or two spaces to start a new sentence.
 126
 127   Avoid line breaks after ``.``, ``?``, and ``!`` signs that do not end
 128   a sentence.  You can escape a line break with a backslash.  In rST,
 129   escaped whitespace is removed, so precede the backslash by a space::
 130
 131     We recommend the works of E. T. A. \
 132     Hoffman.
 133
 134   __ https://www.gnu.org/software/groff/manual/groff.html#Sentences
 135
 136   A man page viewer on a terminal might merge consecutive blank lines,
 137   but this is not done on typesetting devices like printers.  Check your
 138   output with a PostScript or PDF viewer before printing it.
 139
 140 * [LMHT]_ Filenames are always in italics, except in C language
 141   preprocessor inclusions in the SYNOPSIS section.  Use::
 142
 143     .I /usr/include/stdio.h
 144
 145   and::
 146
 147     .B #include <stdio.h>
 148
 149 .. _Docutils: https://docutils.sourceforge.io/