1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
|
.. include:: ../header.rst
==============================
manpage writer for Docutils_
==============================
:Author: Engelbert Gruber
:Contact: docutils-develop@lists.sourceforge.net
:Revision: $Revision: 10086 $
:Date: $Date: 2025-04-14 13:05:01 +0200 (Mo, 14. Apr 2025) $
:Copyright: This document has been placed in the public domain.
This writer generates man pages from reStructuredText. Man pages (short
for "manual pages") are the way Unix systems have provided reference
material to the user on demand, at the shell prompt or in printed and
bound manuals, since 1971. Some GNU projects offer a similar resource
with the Texinfo system.
Man pages are usually formatted with a typesetting language and program
called ``troff``. *man* is a macro package for ``troff``. OpenBSD,
NetBSD, and some GNU/Linux distributions use an alternative program,
``mandoc``, that does not support any typesetting features that cannot
be exercised in a terminal emulator, but supports enough *man* and
``troff`` syntax that it can meet many users' needs. This writer
produces a dialect that is supported by both programs.
Historically, the program for formatting on terminals is called
``nroff``. When details of the output device are not important, we can
refer to the language and its system as *roff*.
.. contents::
Module information
==================
Man pages are organized into numbered sections. A system's *intro*\(1)
or *man*\(1) page lists them. For example, section 1 documents
user commands, and section 3 presents programming library functions.
You will find a "printf" page in both sections; the notations
*printf*\(1) and *printf*\(3) distinguish them.
A man page can discuss several topics; for example, the *gzip*\(1) page
documents the ``gzip``, ``gunzip``, and ``zcat`` commands. A man page's
topic list is followed by a summary description containing key words
that enable the page to located quickly with the ``apropos`` command.
A rST document's title becomes the man page's identifier, and the
subtitle its summary description. The title and docinfo populate the
the man page's header and footer.
Each man page is organized by a standardized set of section headings;
see References_. Use additional section headings at your discretion
only if the standard set does not serve. Man pages support one level of
subsection headings to further organize a section heading's material.
The beginning of a formatted man page might look like this::
man(1) Manual pager utils man(1)
NAME
man - an interface to the system reference manuals
SYNOPSIS
man [-c|-w|-tZT device] [-adhu7V] [-m system[,...]] [-L locale]
It would have a page footer with further information::
noman 1.2.3 2021‐02‐08 man(1)
It could be produced by the following *roff* input.
.. code:: man
.TH man 1 2021-02-08 "noman 1.2.3" "Manual pager utils"
.SH NAME
man \- an interface to the system reference manuals
.SH SYNOPSIS
.B man
.RB [ \-c | \-w | \-tZT
.IR device ]
We can write rST to produce the foregoing.
.. code:: rst
=====
man
=====
--------------------------------------------
an interface to the system reference manuals
--------------------------------------------
:Version: noman 1.2.3
:Date: 2021-02-08
:Manual section: 1
:Manual group: Manual pager utils
SYNOPSIS
========
``man`` ``[-c|-w|-tZT device] [-adhu7V] [-m system[,...]] [-L locale]``
The *man-db* project's own *man* page, which may be installed as
*man*\(1) or *gman*\(1), explains the sectional organization of the
manuals (in both senses).
Configuration
=============
Options can be specified as
* command-line options, or
* configuration settings.
Run ``rst2man --help`` to get a list of available options;
see `Docutils Configuration`_ for details.
.. _Docutils Configuration: config.html
Option ``text-references``, ``macro-references`` set the way
URI-references are typeset in the generated man page.
``text-references``: is the default (for now). A URI-reference would be
typeset::
see Linux Man Page Howto <https://tldp.org/HOWTO/Man-Page/>
``macro-references``: This results in the usage of *man*-macros for
URI-references similar to::
see
.UR https://tldp.org/HOWTO/Man-Page/
Linux Man Page Howto
.UE
The actual typesetting is done by man/roff/mandoc.
In groff 1.23 the macros support OSC8 output, to notify terminals that
some text is a link, similar to html ``<a ref="abc.html">abc</a>``,
``abc.html`` then wouldn't be visible to the user but the terminal
offers opening the standard browser to that URI ... assuming OSC8 is
supported.
Limitations
===========
The "manpage" writer does not support all `Docutils Document Tree`_ elements
but a subset that is relevant for manual pages.
The output is pure text, images are not included. Instead, the text
description in their `"alt" attribute`_ is shown.
A warning is given for image elements without `"alt" attribute`_.
The "manpage" writer ignores element attributes specifying a measure_.
.. _measure: ../ref/doctree.html#measure
.. _"alt" attribute: ../ref/doctree.html#alt
.. groff supports the CSS2 units except "ex", "mm", and "px"
https://www.gnu.org/software/groff/manual/groff.html#Measurements
Conventions
===========
* Newlines, line breaks, and sentences
One should try to comply with the `troff line break rules`__ after
``.``, ``?``, and ``!`` punctuation signs in the rST source. Use a
new line or two spaces to start a new sentence.
Avoid line breaks after ``.``, ``?``, and ``!`` signs that do not end
a sentence. You can escape a line break with a backslash. In rST,
escaped whitespace is removed, so precede the backslash by a space::
We recommend the works of E. T. A. \
Hoffman.
__ https://www.gnu.org/software/groff/manual/groff.html#Sentences
A man page viewer on a terminal might merge consecutive blank lines,
but this is not done on typesetting devices like printers. Check your
output with a PostScript or PDF viewer before printing it.
* Filenames are always in italics, except in C language
preprocessor inclusions in the SYNOPSIS section. [LMHT]_
Use::
.I /usr/include/stdio.h
and::
.B #include <stdio.h>
which would be */usr/include/stdio.h*, typesetting C-code is probably better
passed on to Pygments_.
References
==========
Consult man pages from section 7: *man*, *man-pages*, *groff_man* and
*groff_man_style*.
.. [LMHT] `Linux Man Page Howto <https://tldp.org/HOWTO/Man-Page/>`__.
.. _Pygments: https://pygments.org/
.. _Docutils: https://docutils.sourceforge.io/
.. _Docutils Document Tree: ../ref/doctree.html
|
