Sophie

Sophie

distrib > Mageia > 7 > i586 > media > core-release > by-pkgid > a47d51544ec63a4f57df69ffdfe2c320 > files > 26

aephea-10_008-8.mga7.noarch.rpm

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (c) 2010 Stijn van Dongen -->
<head>
<meta name="keywords" content="manual">
<style type="text/css">
/* START aephea.base.css */
body
{ text-align: justify;
margin-left: 0%;
margin-right: 0%;
}
a:link { text-decoration: none; }
a:active { text-decoration: none; }
a:visited { text-decoration: none; }
a:link { color: #1111aa; }
a:active { color: #1111aa; }
a:visited { color: #111166; }
a.local:link { color: #11aa11; }
a.local:active { color: #11aa11; }
a.local:visited { color: #116611; }
a.intern:link { color: #1111aa; }
a.intern:active { color: #1111aa; }
a.intern:visited { color: #111166; }
a.extern:link { color: #aa1111; }
a.extern:active { color: #aa1111; }
a.extern:visited { color: #661111; }
a.quiet:link { color: black; }
a.quiet:active { color: black; }
a.quiet:visited { color: black; }
div.verbatim
{ font-family: monospace;
margin-top: 1em;
margin-bottom: 1em;
font-size: 10pt;
margin-left: 2em;
white-space: pre;
}
div.indent
{ margin-left: 8%;
margin-right: 0%;
}
.right { text-align: right; }
.left { text-align: left; }
.nowrap { white-space: nowrap; }
.item_leader
{ position: relative;
margin-left: 8%;
}
.item_compact { position: absolute; vertical-align: baseline; }
.item_cascade { position: relative; }
.item_leftalign { text-align: left; }
.item_rightalign
{ width: 2em;
text-align: right;
}
.item_compact .item_rightalign
{ position: absolute;
width: 52em;
right: -2em;
text-align: right;
}
.item_text
{ position: relative;
margin-left: 3em;
}
.smallcaps { font-size: smaller; text-transform: uppercase }
/* END aephea.base.css */
body { font-family: "Garamond", "Gill Sans", "Verdana", sans-serif; }
body
{ text-align: justify;
margin-left: 8%;
margin-right: 8%;
}
</style>
<title>The PUD manual page mini-language</title>
</head>
<body>
<p style="text-align:right">
8 Jan 2010&nbsp;&nbsp;&nbsp;
<a class="local" href="pud-man.ps"><b>pud-man</b></a>
1.002, 10-008
</p>
<div class=" itemize " style="margin-top:1em; font-size:100%">
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">1.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#name">NAME</a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">2.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#description">DESCRIPTION</a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">3.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#macros">MACROS</a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">4.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#seealso">SEE ALSO</a>
</div>
</div>

<a name="name"></a>
<h2>NAME</h2>
<p style="margin-bottom:0" class="asd_par">
pud-man &mdash; A description of the Portable Unix Documentation Language for writing manual pages</p>

<a name="description"></a>
<h2>DESCRIPTION</h2>
<p style="margin-bottom:0" class="asd_par">
This document describes the Portable Unix Documentation (PUD) manual
page mini-language. PUD-man is built on top of the macro interpreter
zoem. A PUD document is generally well-structured, relatively free of
formatting statements, compact to write and easily extendable. It can
be converted to both troff and html, for viewing in terminals and
browsers. High quality Postscript and plain text formats can be derived
from the troff output.</p>
<p style="margin-bottom:0" class="asd_par">
Write your own manual pages by copying the example page
<a class="local" href="buzzz.azm">buzzz.azm</a>
and modifying it to your needs. If you are documenting <i>foo</i>,
the usual approach is to create <i>foo.azm</i>, and from that
create <i>foo.1</i> and <i>foo.html</i> as follows:</p>
<div class="verbatim">   zoem -i foo -d html
   zoem -i foo -d html
   zoem -i foo -d roff -o foo.1
   zoem -i foo -d roff -o foo.1</div>
<p style="margin-top:0em; margin-bottom:0em">
This generates files foo.html and foo.1.
Each device is run twice to be certain that references
are found and linked. PostScript and text versions
can be made from <tt>foo.1</tt> as follows:</p>
<div class="verbatim">   groff -man foo.1 &gt; foo.ps
   groff -t -e -mandoc -Tascii foo.1 | col -bx &gt; foo.txt</div>
<p style="margin-bottom:0" class="asd_par">
Note though that <tt>foo.1</tt> does not use any groff specific
extensions; it should be acceptable input to ancient roffs as well.
Exceptions to this imply a bug in the PUD man macros.</p>
<p style="margin-bottom:0" class="asd_par">
You are advised to start by inspecting a template manual
page such as <a class="local" href="buzzz.azm">buzzz.azm</a>. The current manual
page documents the facilities and macros made available
by the PUD manual language by importing the file <tt>man.zmm</tt>.
The structure of a manual page thus typically looks like this:
</p>
<div class="verbatim">\import{man.zmm}

   \begin{pud::man}{

      {name}{pud-man}
      {html_title}{The PUD manual page mini-language}
      {author}{Stijn van Dongen}
      {section}{7}
      {year}{2009}
      {month}{Jan}
      {day}{15}
      {tag}{1.002}
      {stamp}{09-015}
      {defstyle}{long}
      {synstyle}{long}

   }

   \${html}{\"pud::man::maketoc"}

   \sec{name}{NAME}
   \NAME{pud-man}{A description of the Portable Unix Documentation Language for writing manual pages}

   \sec{description}{DESCRIPTION}
   \par{ .....  .....}

   \sec{some}{SECTION}
   \par{ .....  .....}
    
   \end{pud::man}</div>
<p style="margin-top:0em; margin-bottom:0em">
The PUD manual page macro package automatically imports a set of generic
macros from the <tt>aephea-base</tt> and <tt>aephea-ref</tt> packages. The
<a class="local sibling" href="aephea-base.html">aephea-base</a> and <a class="local sibling" href="aephea-ref.html">aephea-ref</a> manual pages document those
macros, which are also essential for writing manual pages. The most
important are
</p>
<div class=" itemize " style="margin-top:1em; font-size:100%">
<div class=" item_compact"><div class=" item_rightalign " style="right:-1em">i)</div></div>
<div class=" item_text " style="margin-left:3em">
<p style="margin-top:0em; margin-bottom:0em">
The <i>itemize</i> environment
(used as <tt>\begin{itemize}[{options}] ... \end{itemize}</tt>)
and its associated macros
<tt>\item#1</tt>, <tt>\items#1</tt>, <tt>\item</tt>
<tt>\itemskip</tt>, <tt>\intermezzo</tt>, and others.</p>
</div>
<div style="margin-top:0em">&nbsp;</div><div class=" item_compact"><div class=" item_rightalign " style="right:-1em">ii)</div></div>
<div class=" item_text " style="margin-left:3em">
<p style="margin-top:0em; margin-bottom:0em">
The font style/appearance macros <tt>\bf#1</tt>, <tt>\it#1</tt>, <tt>\tt#1</tt>,
<tt>\v#1</tt>, the font size macros <tt>\ftinc#2</tt> and <tt>\ftdec#2</tt>.
</p>
</div>
<div style="margin-top:0em">&nbsp;</div><div class=" item_compact"><div class=" item_rightalign " style="right:-1em">iii)</div></div>
<div class=" item_text " style="margin-left:3em">
<p style="margin-top:0em; margin-bottom:0em">
The paragraph mark <tt>\par#1</tt> (required for each paragraph).
</p>
</div>
<div style="margin-top:0em">&nbsp;</div><div class=" item_compact"><div class=" item_rightalign " style="right:-1em">iv)</div></div>
<div class=" item_text " style="margin-left:3em">
<p style="margin-top:0em; margin-bottom:0em">
The verbatim macros <tt>\verbatim#1</tt> and <tt>\verbatix#1</tt>.
</p>
</div>
<div style="margin-top:0em">&nbsp;</div><div class=" item_compact"><div class=" item_rightalign " style="right:-1em">v)</div></div>
<div class=" item_text " style="margin-left:3em">
<p style="margin-top:0em; margin-bottom:0em">
The link macros <tt>\httpref#1</tt>, <tt>\sibref#2</tt>, <tt>\iref#2</tt>,
<tt>\lref#2</tt>, <tt>\aref#2</tt>.
</p>
</div>
<div style="margin-top:0em">&nbsp;</div><div class=" item_compact"><div class=" item_rightalign " style="right:-1em">vi)</div></div>
<div class=" item_text " style="margin-left:3em">
<p style="margin-top:0em; margin-bottom:0em">
In <a class="local sibling" href="aephea-ref.html">aephea-ref</a> the pair of <tt>\reference#2</tt> and <tt>\refer#1</tt>.
</p>
</div>
</div>
<p style="margin-bottom:0" class="asd_par">
For the authorative listing consult the <a class="local sibling" href="aephea-base.html">aephea-base</a>
manual page. The listing above includes a silly demonstration of some
itemize features such as alignment and automatic numbering. Read the
<a class="local sibling" href="../doc/zum.html">Zoem User Manual</a> for a better understanding of
zoem macro packages and the design of zoem.
</p>

<a name="macros"></a>
<h2>MACROS</h2>
<div class=" itemize " style="margin-top:1em; font-size:100%">
<p style="margin-bottom:0" class="asd_par">
The <tt>\$man</tt> key in the <tt>pud::man</tt> environment can be used to set the
centered heading found in all UNIX roff manual pages. If not set, a heading
is derived from the <tt>\$section</tt> macro. Below is the listing of default
headers. It can probably be improved.
</p>
<div class="verbatim">      1     USER COMMANDS
      2     SYSTEM CALLS
      3     LIBRARY CALLS
      4     SPECIAL FILES
      5     FILE FORMATS
      6     GAMES
      7     MACRO PACKAGES
      8     SYSTEM ADMINISTRATION
      9     KERNEL ROUTINES</div>
<p style="margin-bottom:0" class="asd_par">
The last textual item in a manual page must be the macro
<tt>\"man::postamble"</tt>.
See the example page <a class="local" href="buzzz.azm">buzzz.azm</a>.
</p>
<div class=" item_cascade item_leftalign nowrap" ><tt>\sec#2</tt></div><div class=" item_cascade item_leftalign nowrap" ><tt>\secref#1</tt></div>
<div class=" item_text " style="margin-left:2em">
<p style="margin-top:0em; margin-bottom:0em">
Start a section, refer to a section. The first argument of <tt>\sec#2</tt> is
the anchor for that section, the second argument is the title. The macro
<tt>\secref#1</tt> takes an anchor and outputs the title of the associated
section.
</p>
<p style="margin-bottom:0" class="asd_par">
The NAME section should be written like the example below, taken
from the zoem interpreter manual.
</p>
<div class="verbatim">
\sec{name}{NAME}
\NAME{zoem}{interpreter for the Zoem macro/programming language.}</div>
<p style="margin-top:0em; margin-bottom:0em">
Usage of the NAME macro ensures that the troff output
complies with the format expected by <b>apropos</b>.
</p>
</div>
<div style="margin-top:0em">&nbsp;</div><div class=" item_cascade item_leftalign nowrap" ><tt>\defopt#2</tt></div><div class=" item_cascade item_leftalign nowrap" ><tt>\defopt#3</tt></div><div class=" item_cascade item_leftalign nowrap" ><tt>\defkvp#3</tt></div>
<div class=" item_text " style="margin-left:2em">
<p style="margin-top:0em; margin-bottom:0em">
Write entry in the options section. typical usage is within an <tt>\item#1</tt>
macro. For all macros the first argument is the option being described,
and the last argument is a short string describing the option. This string
is printed in case the macro <tt>\"man::defstyle"</tt> is set to <tt>long</tt>. The
macro <tt>\defopt#3</tt> is used for options taking arguments; the second
argument is the name describing the argument.
The macro <tt>\defkvp#3</tt> is used for long options of the form
<tt>--mode=str</tt>, which you would enter as
<tt>\defkvp{mode}{str}{set foo mode}</tt>. Long options of the form
<tt>--verbose</tt> are simply entered using <tt>\defopt#2</tt>.</p>
</div>
<div style="margin-top:0em">&nbsp;</div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><tt>\optref#2</tt></div></div>
<div class=" item_text " style="margin-left:2em">
<p style="margin-top:0em; margin-bottom:0em">
Refer to an option. The first argument is the option, the second argument
is the text associated with the link. This text will indeed be linking
in html, but nothing special will happen in troff - the text is printed
as is.</p>
</div>
<div style="margin-top:0em">&nbsp;</div><div class=" item_cascade item_leftalign nowrap" ><tt>\synoptopt#2</tt></div><div class=" item_cascade item_leftalign nowrap" ><tt>\synoptopt#3</tt></div><div class=" item_cascade item_leftalign nowrap" ><tt>\synreqopt#2</tt></div><div class=" item_cascade item_leftalign nowrap" ><tt>\synreqopt#3</tt></div>
<div class=" item_text " style="margin-left:2em">
Write entries in the synopsis section. This assumes that somewhere
an option was created using one of the <tt>defopt</tt> family members
described below.
<p style="margin-bottom:0" class="asd_par">
For all 'syn' options the first argument is simply the option itself. From
this argument the anchor is reconstructed that was created by one of the
<tt>defopt</tt> macros. The last argument is always a short string describing
the option. It depends on the style chosen, i.e. whether
<tt>\"man::synstyle"</tt> is <tt>long</tt> or <tt>short</tt>, whether this string shows up
or not. The macros in this group that take two arguments describe unary
options that take no argument. The macros taking three arguments describe
options that do take an argument.</p>
<p style="margin-bottom:0" class="asd_par">
Here is an example from the zoem manual page:</p>
<div class="verbatim">\synoptopt{--trace}{trace mode, default}
\synoptopt{--trace-all-long}{long trace mode}
\synoptopt{--trace-all-short}{short trace mode}
\synoptopt{--trace-regex}{trace regexes}
\synoptopt{--show-tracebits}{show trace bits}
\synoptopt{-trace}{k}{trace mode, explicit}
\synoptopt{--stats}{show symbol table stats after run}</div>
</div>
<div style="margin-top:0em">&nbsp;</div><div class=" item_cascade item_leftalign nowrap" ><tt>\"man::synstyle"</tt></div><div class=" item_cascade item_leftalign nowrap" ><tt>\"man::defstyle"</tt></div>
<div class=" item_text " style="margin-left:2em">
<p style="margin-top:0em; margin-bottom:0em">
Before importing the manual macros, set these to your prefered
style. Each of these should be set either to <tt>short</tt> or <tt>long</tt>.</p>
</div>
<div style="margin-top:0em">&nbsp;</div><div class=" item_cascade item_leftalign nowrap" ><tt>\genopt#1</tt></div><div class=" item_cascade item_leftalign nowrap" ><tt>\genopt#2</tt></div><div class=" item_cascade item_leftalign nowrap" ><tt>\genarg#1</tt></div><div class=" item_cascade item_leftalign nowrap" ><tt>\useopt#1</tt></div><div class=" item_cascade item_leftalign nowrap" ><tt>\useopt#2</tt></div><div class=" item_cascade item_leftalign nowrap" ><tt>\usearg#1</tt></div><div class=" item_cascade item_leftalign nowrap" ><tt>\genkvp#2</tt></div><div class=" item_cascade item_leftalign nowrap" ><tt>\usekvp#2</tt></div>
<div class=" item_text " style="margin-left:2em">
<p style="margin-top:0em; margin-bottom:0em">
These are for creating a consistent style when refering to options. One is
free to disregard these altogether. They are meant as convenience, but some
may find the extra typing annoying.</p>
<p style="margin-bottom:0" class="asd_par">
The idea is that the 'gen' macros are used when generic mention is
made of an option and possibly its argument.
The 'use' macros are used when explicit usage is mentioned.
An example is the following:</p>
<div style="
margin-left:2em;
margin-right:3em;
">
<p style="margin-bottom:0" class="asd_par">
Modes can be chosen using <b>-mode</b>&nbsp;<i>str</i> where <i>str</i> is any of
<b>small</b>, <b>medium</b>, or <b>large</b>. Use
<b>-mode</b>&nbsp;<b>small</b> if your hardware is outdated.</p>
<p style="margin-bottom:0" class="asd_par">
Use <b>--mileage</b>=<i>str</i> to set the mileage, e.g. <b>--mileage</b>=<b>high</b>
or <b>--mileage</b>=<b>astronomical</b>.</p>
</div>
</div>
</div>

<a name="seealso"></a>
<h2>SEE ALSO</h2>
<p style="margin-bottom:0" class="asd_par">
The <a class="local sibling" href="pud.html">pud</a> manual page gives an overview of PUD.</p>
</body>
</html>

Perl :: Catalyst :: PostgreSQL :: RPM Valid HTML 4.01 Transitional