chunked/ch24.html


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

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!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"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 24. Manpage Documents</title><link rel="stylesheet" type="text/css" href="docbook-xsl.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.79.1" /><link rel="home" href="index.html" title="AsciiDoc User Guide" /><link rel="up" href="index.html" title="AsciiDoc User Guide" /><link rel="prev" href="ch23.html" title="Chapter 23. Tables" /><link rel="next" href="ch25.html" title="Chapter 25. Mathematical Formulas" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><td width="20%" align="left"><a accesskey="p" href="ch23.html"><img src="images/icons/prev.png" alt="Prev" /></a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ch25.html"><img src="images/icons/next.png" alt="Next" /></a></td></tr></table><hr /></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="X1"></a>Chapter 24. Manpage Documents</h1></div></div></div><p>Sooner or later, if you program in a UNIX environment, you’re going
to have to write a man page.</p><p>By observing a couple of additional conventions (detailed below) you
can write AsciiDoc files that will generate HTML and PDF man pages
plus the native manpage roff format.  The easiest way to generate roff
manpages from AsciiDoc source is to use the a2x(1) command. The
following example generates a roff formatted manpage file called
<code class="literal">asciidoc.1</code> (a2x(1) uses asciidoc(1) to convert <code class="literal">asciidoc.1.txt</code> to
DocBook which it then converts to roff using DocBook XSL Stylesheets):</p><pre class="literallayout">a2x --doctype manpage --format manpage asciidoc.1.txt</pre><div class="sidebar"><div class="titlepage"><div><div><p class="title"><strong>Viewing and printing manpage files</strong></p></div></div></div><p>Use the <code class="literal">man(1)</code> command to view the manpage file:</p><pre class="literallayout">$ man -l asciidoc.1</pre><p>To print a high quality man page to a postscript printer:</p><pre class="literallayout">$ man -l -Tps asciidoc.1 | lpr</pre><p>You could also create a PDF version of the man page by converting
PostScript to PDF using <code class="literal">ps2pdf(1)</code>:</p><pre class="literallayout">$ man -l -Tps asciidoc.1 | ps2pdf - asciidoc.1.pdf</pre><p>The <code class="literal">ps2pdf(1)</code> command is included in the Ghostscript distribution.</p></div><p>To find out more about man pages view the <code class="literal">man(7)</code> manpage
(<code class="literal">man 7 man</code> and <code class="literal">man man-pages</code> commands).</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_document_header"></a>24.1. Document Header</h2></div></div></div><p>A manpage document Header is mandatory. The title line contains the
man page name followed immediately by the manual section number in
brackets, for example <span class="emphasis"><em>ASCIIDOC(1)</em></span>. The title name should not contain
white space and the manual section number is a single digit optionally
followed by a single character.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_the_name_section"></a>24.2. The NAME Section</h2></div></div></div><p>The first manpage section is mandatory, must be titled <span class="emphasis"><em>NAME</em></span> and must
contain a single paragraph (usually a single line) consisting of a
list of one or more comma separated command name(s) separated from the
command purpose by a dash character. The dash must have at least one
white space character on either side. For example:</p><pre class="literallayout">printf, fprintf, sprintf - print formatted output</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_the_synopsis_section"></a>24.3. The SYNOPSIS Section</h2></div></div></div><p>The second manpage section is mandatory and must be titled <span class="emphasis"><em>SYNOPSIS</em></span>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_refmiscinfo_attributes"></a>24.4. refmiscinfo attributes</h2></div></div></div><p>In addition to the automatically created man page <a class="link" href="ch31.html" title="Chapter 31. Intrinsic Attributes">intrinsic attributes</a> you can assign DocBook
<a class="ulink" href="https://tdg.docbook.org/tdg/4.5/refmiscinfo.html" target="_top">refmiscinfo</a>
element <span class="emphasis"><em>source</em></span>, <span class="emphasis"><em>version</em></span> and <span class="emphasis"><em>manual</em></span> values using AsciiDoc
<code class="literal">{mansource}</code>, <code class="literal">{manversion}</code> and <code class="literal">{manmanual}</code> attributes
respectively. This example is from the AsciiDoc header of a man page
source file:</p><pre class="literallayout">:man source:   AsciiDoc
:man version:  {revnumber}
:man manual:   AsciiDoc Manual</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch23.html"><img src="images/icons/prev.png" alt="Prev" /></a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ch25.html"><img src="images/icons/next.png" alt="Next" /></a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/icons/home.png" alt="Home" /></a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>