| Server IP : 82.148.16.210 / Your IP : 216.73.217.15 Web Server : nginx/1.29.5 System : Linux mail.sarafai.ru 6.1.0-43-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.162-1 (2026-02-08) x86_64 User : www-data ( 33) PHP Version : 7.4.33 Disable Function : pcntl_alarm,pcntl_fork,pcntl_waitpid,pcntl_wait,pcntl_wifexited,pcntl_wifstopped,pcntl_wifsignaled,pcntl_wifcontinued,pcntl_wexitstatus,pcntl_wtermsig,pcntl_wstopsig,pcntl_signal,pcntl_signal_get_handler,pcntl_signal_dispatch,pcntl_get_last_error,pcntl_strerror,pcntl_sigprocmask,pcntl_sigwaitinfo,pcntl_sigtimedwait,pcntl_exec,pcntl_getpriority,pcntl_setpriority,pcntl_async_signals,pcntl_unshare, MySQL : OFF | cURL : ON | WGET : ON | Perl : ON | Python : ON | Sudo : ON | Pkexec : OFF Directory : /proc/thread-self/root/usr/share/doc/python3-docutils/docs/user/ |
Upload File : |
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<title>manpage writer for Docutils</title>
<meta name="author" content="Engelbert Gruber" />
<meta name="date" content="2022-05-30" />
<meta name="copyright" content="This document has been placed in the public domain." />
<link rel="stylesheet" href="../../css/html4css1.css" type="text/css" />
</head>
<body>
<div class="header">
<a class="reference external" href="https://docutils.sourceforge.io">Docutils</a> | <a class="reference external" href="../index.html">Overview</a> | <a class="reference external" href="../index.html#project-fundamentals">About</a> | <a class="reference external" href="../index.html#user">Users</a> | <a class="reference external" href="../index.html#ref">Reference</a> | <a class="reference external" href="../index.html#howto">Developers</a>
<hr class="header"/>
</div>
<div class="document" id="manpage-writer-for-docutils">
<h1 class="title">manpage writer for <a class="reference external" href="https://docutils.sourceforge.io/">Docutils</a></h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>Engelbert Gruber</td></tr>
<tr><th class="docinfo-name">Contact:</th>
<td><a class="first last reference external" href="mailto:docutils-develop@lists.sourceforge.net">docutils-develop@lists.sourceforge.net</a></td></tr>
<tr><th class="docinfo-name">Revision:</th>
<td>9059</td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2022-05-30</td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>This document has been placed in the public domain.</td></tr>
</tbody>
</table>
<!-- Minimal menu bar for inclusion in documentation sources
in ``docutils/docs/*/`` sub-diretories.
Attention: this is not a standalone document. -->
<p>This writer explores the possibilities 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.</p>
<div class="contents topic" id="contents">
<p class="topic-title">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#module-information" id="toc-entry-1">Module information</a></li>
<li><a class="reference internal" href="#references" id="toc-entry-2">References</a></li>
<li><a class="reference internal" href="#conventions" id="toc-entry-3">Conventions</a></li>
<li><a class="reference internal" href="#todo-open-issues" id="toc-entry-4">TODO - Open issues</a></li>
</ul>
</div>
<div class="section" id="module-information">
<h1><a class="toc-backref" href="#toc-entry-1">Module information</a></h1>
<p>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 program <tt class="docutils literal">apropos</tt>, therefore the headline
should contain a short text describing into which group this command belongs.</p>
<p>That information is collected from the title, subtitle and docinfo.</p>
<p>Also man pages have a defined set of sections, that are more or less
mandatory, see <a class="reference internal" href="#references">References</a>.</p>
<p>man pages look like:</p>
<pre class="literal-block">
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]
</pre>
<p>in roff formatting:</p>
<pre class="literal-block">
.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 \|]
</pre>
<p>This means we have</p>
<ul class="simple">
<li>a title "man"</li>
<li>a subtitle "an interface to the on-line reference manuals"</li>
<li>a manual section "1"</li>
<li>a manual group "Manual pager utils"</li>
<li>a date "14 May 2001"</li>
<li>a version "2.3.19"</li>
</ul>
</div>
<div class="section" id="references">
<h1><a class="toc-backref" href="#toc-entry-2">References</a></h1>
<p>man pages from section 7, <tt class="docutils literal">man</tt> and <tt class="docutils literal"><span class="pre">man-pages</span></tt>.</p>
<table class="docutils citation" frame="void" id="lmht" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#citation-reference-1">[LMHT]</a></td><td><a class="reference external" href="https://tldp.org/HOWTO/Man-Page/">Linux Man Page Howto</a>.</td></tr>
</tbody>
</table>
</div>
<div class="section" id="conventions">
<h1><a class="toc-backref" href="#toc-entry-3">Conventions</a></h1>
<ul>
<li><p class="first">man pages have a special structure and organization. From the manpage
to <em>man</em>:</p>
<pre class="literal-block">
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.
</pre>
</li>
<li><p class="first">new lines in general.</p>
<p>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.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<ol class="arabic simple">
<li>Roff requests only work when at line start.</li>
<li>But consecutive blank lines are merged by the viewer but not on
printouts.</li>
</ol>
<p class="last">So try the rule start new lines in <tt class="docutils literal">visit_</tt>-functions, but only if
necessary. E.g. <tt class="docutils literal"><span class="pre">field-names</span></tt> are already on a new line because of
docutils structure.</p>
</div>
</li>
<li><p class="first">Indentation, left margin:</p>
<ul>
<li><p class="first">The writer includes two macros <tt class="docutils literal">.INDENT</tt> and <tt class="docutils literal">.UNINDENT</tt> that
keep track of the indentation in roff-code, for line-blocks python
keeps track of it. WHAT should be the preferred way ?</p>
<p>But standard macros like <tt class="docutils literal">.PP</tt> might reset it.</p>
</li>
<li><p class="first">Why do <tt class="docutils literal">.RE</tt> and <tt class="docutils literal">.RS</tt> not work?</p>
</li>
</ul>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Current indent is in register <tt class="docutils literal">.i</tt>.</p>
</div>
</li>
<li><p class="first"><a class="citation-reference" href="#lmht" id="citation-reference-1">[LMHT]</a> Filenames are always in italics, except in the SYNOPSIS section,
use:</p>
<pre class="literal-block">
.I /usr/include/stdio.h
</pre>
<p>and:</p>
<pre class="literal-block">
.B #include <stdio.h>
</pre>
</li>
<li><p class="first">Tables are possible, via the external processor tbl, although one should
avoid them.</p>
</li>
</ul>
</div>
<div class="section" id="todo-open-issues">
<h1><a class="toc-backref" href="#toc-entry-4">TODO - Open issues</a></h1>
<ul>
<li><p class="first">How to escape double quotes in macro arguments ?</p>
</li>
<li><p class="first">Typeset URLs : <tt class="docutils literal">man 7 man</tt> on linux says use <tt class="docutils literal">.UR</tt> and <tt class="docutils literal">.UE</tt>.</p>
</li>
<li><p class="first">How to typeset command/manpage names in text.</p>
</li>
<li><p class="first">How to write long syntax lines.</p>
</li>
<li><p class="first">Line ends around email or web addresses in texts.
How to distinguish something is inline or not ?</p>
</li>
<li><p class="first">Images and equations are discouraged.</p>
</li>
<li><p class="first">Lists in admonitions are not intended.</p>
</li>
<li><p class="first">Encoding declaration <tt class="docutils literal">'\" t <span class="pre">-*-</span> coding: <span class="pre">ISO-8859-1</span> <span class="pre">-*-</span></tt>
in first line.</p>
<p>BUT if UTF-8 is declared tables are no longer processed.</p>
</li>
<li><p class="first">Input and output encoding are problematic at least.</p>
</li>
</ul>
</div>
</div>
</body>
</html>