|Copyright:||This document has been placed in the public domain.|
This tries to explore the posibilities to generate man-pages from reStructuredText. Man pages are the way for Unix systems to provide help to the user. GNU does this with (TeX)info-pages.
Unix man page belong into a numbered section, 1 is user commands, 8 contains administrator commands, the headlines of all manpages are collected into a database, queryable with the programm apropos, therefore the headline should contain a short text describing into which group this command belongs.
These informations are collected from title, subtitle and the docinfo.
Also man pages have a defined set of sections, that are more or less mandatory, see References.
man pages look like:
man(1) Man Pager Utils man(1) NAME man - an interface to the on-line reference manuals SYNOPSIS man [-c|-w|-tZT device] [-adhu7V] [-m system[,...]] [-L locale]
in roff formatting:
.TH man 1 "14 May 2001" "2.3.19" "Manual pager utils" .SH NAME man \- an interface to the on-line reference manuals .SH SYNOPSIS .\" The general command line .B man .RB [\| \-c \||\| \-w \||\| \-tZT .IR device \|]
This means we have
- a title “man”
- a subtitle “an interface to the on-line reference manuals”
- a manual section “1”
- a manual group “Manual pager utils”
- a date “14 May 2001”
- a version “2.3.19”
man pages have a special structure and organization. From the manpage to man:
The table below shows the section numbers of the manual followed by the types of pages they contain. 1 Executable programs or shell commands 2 System calls (functions provided by the kernel) 3 Library calls (functions within program libraries) 4 Special files (usually found in /dev) 5 File formats and conventions eg /etc/passwd 6 Games 7 Miscellaneous (including macro packages and conven- tions), e.g. man(7), groff(7) 8 System administration commands (usually only for root) 9 Kernel routines [Non standard] A manual page consists of several parts. They may be labelled NAME, SYNOPSIS, DESCRIPTION, OPTIONS, FILES, SEE ALSO, BUGS, and AUTHOR. The following conventions apply to the SYNOPSIS section and can be used as a guide in other sections. bold text type exactly as shown. italic text replace with appropriate argument. [-abc] any or all arguments within [ ] are optional. -a|-b options delimited by | cannot be used together. argument ... argument is repeatable. [expression] ... entire expression within [ ] is repeatable. The command or function illustration is a pattern that should match all possible invocations. In some cases it is advisable to illustrate sev- eral exclusive invocations as is shown in the SYNOPSIS section of this manual page.
new lines in general.
Consecutive blank lines are merged by the viewer but not on printouts. So one has to be cautious. This is most disturbing when printing postscript.
- Roff requests only work when at line start.
- But consecutive blank lines are merged by the viewer but not on printouts.
So try the rule start new lines in visit_-functions, but only if necessary. E.g. field-names are already on a new line because of docutils structure.
Indentation, left margin:
The writer includes two macros .INDENT and .UNINDENT that keep track of the indentation in roff-code, for line-blocks python keeps track of it. WHAT should be the preferred way ?
But standard macros like .PP might reset it.
Why do .RE and .RS not work?
Current indent is in register .i.
[LMHT] Filenames are always in italics, except in the SYNOPSIS section, use:
.B #include <stdio.h>
Tables are possible, via the external processor tbl, although one should avoid them.
How to typeset command/manpage names in text.
How to write long syntax lines.
Line ends around email or web addresses in texts. How to distinguish something is inline or not ?
Images and equations are discouraged.
Lists in admonitions are not intended.
Encoding declaration '\" t -*- coding: ISO-8859-1 -*- in first line.
BUT if UTF-8 is declared tables are no longer processed.
Input and output encoding are problematic at least.