You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
163 lines
5.0 KiB
163 lines
5.0 KiB
============================== |
|
manpage writer for Docutils_ |
|
============================== |
|
|
|
:Author: Engelbert Gruber |
|
:Contact: docutils-develop@lists.sourceforge.net |
|
:Revision: $Revision: 7302 $ |
|
:Date: $Date: 2012-01-03 20:23:53 +0100 (Di, 03 Jan 2012) $ |
|
: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. |
|
|
|
Module information |
|
'''''''''''''''''' |
|
|
|
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" |
|
|
|
References |
|
'''''''''' |
|
|
|
man pages from section 7, ``man`` and ``man-pages``. |
|
|
|
.. [LMHT] Linux Man Page Howto. |
|
|
|
Conventions |
|
''''''''''' |
|
|
|
* 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. |
|
|
|
.. NOTE:: |
|
|
|
1. Roff requests only work when at line start. |
|
2. 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? |
|
|
|
.. Note:: |
|
Current indent is in register ``.i``. |
|
|
|
* [LMHT]_ Filenames are always in italics, except in the SYNOPSIS section, |
|
use:: |
|
|
|
.I /usr/include/stdio.h |
|
|
|
and:: |
|
|
|
.B #include <stdio.h> |
|
|
|
* Tables are possible, via the external processor tbl, although one should |
|
avoid them. |
|
|
|
Open issues |
|
''''''''''' |
|
|
|
* 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. |
|
|
|
.. _Docutils: http://docutils.sourceforge.net/
|
|
|