File: index.html

package info (click to toggle)
zoem 07-333-3
links: PTS
area: main
in suites: lenny
size: 2,700 kB
ctags: 2,050
sloc: ansic: 17,942; sh: 790; makefile: 228
file content (326 lines) | stat: -rw-r--r-- 15,859 bytes
parent folder | download | duplicates (2)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<!-- Copyright (c) 2007 Stijn van Dongen -->
<head>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<style type="text/css">
body {
text-align: justify;
color: #001111;
background: white;
margin-left: 8%;
margin-right: 8%;
font-family: Helvetica, Univers, Verdana, sans-serif;
}
p.default {
font-family: Helvetica, Univers, Verdana, sans-serif;
text-align: justify;
}
p.L53 { font-size: 30pt; }
p.L52 { font-size: 20pt; }
p.L51 { font-size: 15pt; }
p.L50 { font-size: 12pt; }
p.L49 { font-size: 10pt; }
p.L48 { font-size: 9pt; }
p.L47 { font-size: 8pt; }
td {
font-family: Helvetica, Univers, Verdana, sans-serif;
text-align: justify;
}
h3 { margin-top:1em; }
h2 { margin-top:2em; }
.left { text-align: left; align: left; }
.right { text-align: right; align: right; }
.center { text-align: center; align: center; }
.nowrap { white-space: nowrap; }
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.copy
{ font-size: 12pt;
font-family: monospace;
text-align: left;
white-space: pre;
margin-left: 2em;
margin-top: 1em;
margin-bottom: 1em;
}
div.indent
{ margin-left: 8%;
margin-right: 0%;
}
</style>
<title>Portable Unix Documentation</title>
</head>
<body>
<p style="text-align:right">
29 Nov 2007&nbsp;&nbsp;&nbsp;
<a class="local" href="pud.ps"><b>pud</b></a>
1.002, 07-333
</p>

<a name="name"></a>
<h2>NAME</h2>
<p class="default L50" style="margin-bottom:0">
pud - Portable Unix Documentation for manual pages and FAQ documents</p>

<a name="description"></a>
<h2>DESCRIPTION</h2>
<p class="default L50" style="margin-bottom:0">
Portable Unix Documentation or PUD currently provides two
mini-languages for authoring in the UNIX environment.
The two mini-languages are for writing UNIX manual pages and FAQ documents.
Source documents in PUD languages can be compiled to either
cross-linked html or to troff. The troff output can be further compiled
into PostScript, PDF, and plain text.</p>

<a name="toc"></a>
<h2>Table of Contents</h2>
<div style="margin-top:1em">
<table
cellspacing="0" border=0
cellpadding="0" summary="itemize">
<tr><td width=48 valign="top" class="left nowrap">1.</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<a class="intern" href="#name">NAME</a>
</div></td></tr><tr><td width=48 valign="top" class="left nowrap">2.</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<a class="intern" href="#description">DESCRIPTION</a>
</div></td></tr><tr><td width=48 valign="top" class="left nowrap">3.</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<a class="intern" href="#toc">Table of Contents</a>
</div></td></tr><tr><td width=48 valign="top" class="left nowrap">4.</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<a class="intern" href="#zoem">Portable Unix Documentation extends zoem</a>
</div></td></tr><tr><td width=48 valign="top" class="left nowrap">5.</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<a class="intern" href="#started">Getting started</a>
</div></td></tr><tr><td width=48 valign="top" class="left nowrap">6.</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<a class="intern" href="#man">Unix manual pages in html, troff and PostScript</a>
</div></td></tr><tr><td width=48 valign="top" class="left nowrap">7.</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<a class="intern" href="#faq">FAQ documents in html, troff and PostScript</a>
</div></td></tr><tr><td width=48 valign="top" class="left nowrap">8.</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<a class="intern" href="#elsewhere">Manuals and FAQ examples elsewhere</a>
</div></td></tr><tr><td width=48 valign="top" class="left nowrap">9.</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<a class="intern" href="#dch">DocBook considered harmful</a>
</div></td></tr><tr><td width=48 valign="top" class="left nowrap">10.</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<a class="intern" href="#info">Info evil</a>
</div></td></tr><tr><td width=48 valign="top" class="left nowrap">11.</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<a class="intern" href="#author">AUTHOR</a>
</div></td></tr><tr><td width=48 valign="top" class="left nowrap">12.</td><td width=8>&nbsp;</td><td><div style="text-align:justify">
<a class="intern" href="#seealso">SEE ALSO</a>
</div></td></tr>
</table>

</div>

<a name="zoem"></a>
<h2>Portable Unix Documentation extends zoem</h2>
<p class="default L50" style="margin-bottom:0">
Portable Unix Documentation is built on top of
<a class="extern" href="http://micans.org/zoem">zoem</a>, an all-purpose
macro/programming language. PUD documents are processed by compiling
them with the zoem processor.
The documents themselves are generally well-structured, relatively free
of formatting statements and compact to write.
They can be easily extended since the full zoem language is available
from within a portable unix document.</p>
<p class="default L50" style="margin-bottom:0">
Portable Unix Documentation is currently shipped with zoem. To use it
you need zoem and if you install zoem you automatically get PUD. The
upside is that the language files locations (which must be imported in
a PUD document) are compiled into zoem and zoem and PUD will work
seamlessly together.</p>

<a name="started"></a>
<h2>Getting started</h2>
<div style="margin-top:1em">
<table
cellspacing="0" border=0
cellpadding="0" summary="itemize">
<tr><td width=32 valign="top" class=right>i</td><td width=24>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
Get and install
<a class="extern" href="http://micans.org/zoem">zoem</a>.
All PUD files will be installed as well. If you are reading this
locally on your system, chances are zoem and PUD are installed.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=24>&nbsp;</td><td></td></tr><tr><td width=32 valign="top" class=right>ii</td><td width=24>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
On this page read the pointers in section
<a class="intern" href="#man">Section&nbsp;6</a> if you want to write a manual page.
Read the pointers in section <a class="intern" href="#faq">Section&nbsp;7</a> if you
want to write an FAQ. The fastest way to get up to speed is to copy and
modify a template or existing source document.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=24>&nbsp;</td><td></td></tr><tr><td width=32 valign="top" class=right>iii</td><td width=24>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
While writing your document, consult
the <a class="local" href="pud-man.html">pud-man</a> documentation,
the <a class="local" href="pud-faq.html">pud-faq</a> documentation,
and the <a class="local" href="pud-base.html">pud-base</a> documentation as necessary.</p>
</div></td></tr><tr><td width=32>&nbsp;</td><td width=24>&nbsp;</td><td></td></tr><tr><td width=32 valign="top" class=right>iv</td><td width=24>&nbsp;</td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
Off you go. If you need macro
facilities or programming facilities, zoem is there to assist you.
Simple macro tasks are easy to accomplish. For more involved stuff you
might want to consult the Zoem User Manual (or ZUM).
ZUM should be installed
<a class="local" href="../doc/zum.html">locally</a>.
Alternatively view the latest ZUM
<a class="extern" href="http://micans.org/zoem/doc/zum.html">at micans</a>
or subscribe to the mailing list
(<a class="extern" href="http://micans.org/zoem/index.html#list">http://micans.org/zoem/index.html#list</a>).</p>
</div></td></tr>
</table>

</div>

<a name="man"></a>
<h2>Unix manual pages in html, troff and PostScript</h2>
<p class="default L50" style="margin-bottom:0">
With the <a class="local" href="pud-man.html">pud-man</a>
package you create manual pages for output in either
<i>troff</i> (groff, nroff) or html. The first can be viewed from a
terminal, the second in a browser.</p>
<p class="default L50" style="margin-bottom:0">
The fictitious <i>buzzz</i> utility is described in a PUD manual
page. It is shipped with every zoem distribution and the buzzz
manual page should be installed <a class="local" href="buzzz.html">locally</a>
in the same location as <a class="local" href="buzzz.azm">its source</a>.
If the location is hard to find you can just obtain the
PUD source from the zoem source distribution, or alternatively
you may view the latest
<a class="extern" href="http://micans.org/zoem/mac/buzzz.azm">buzzz source</a>
upstream at micans.
Further local links are to the
<a class="local" href="buzzz.ps">PostScript version</a> and the
<a class="local" href="buzzz.txt">plain text format</a>.</p>
<p class="default L50" style="margin-bottom:0">
For other examples consider the oldest PUD manual page ever written: the
<a class="extern" href="http://micans.org/mcl/man/mcl.html">MCL manual page</a>,
the same in
<a class="extern" href="http://micans.org/mcl/man/mcl.ps">PostScript output</a>,
and the
<a class="extern" href="http://micans.org/mcl/man/mcl.azm">source for all this</a>.
By using the venerable <i>col</i> program, the troff output
can be converted to nice looking
<a class="extern" href="http://micans.org/mcl/man/mcl.txt">plain text format</a>.
Find the
<a class="extern" href="http://micans.org/mcl/man/mcl.1">troff output</a> disclosed as well.</p>
<p class="default L50" style="margin-bottom:0">
There are some 20+ manual pages for
<a class="extern" href="http://micans.org/mcl/man/">different utilities in the mcl family</a>.</p>

<a name="faq"></a>
<h2>FAQ documents in html, troff and PostScript</h2>
<p class="default L50" style="margin-bottom:0">
Create FAQ documents with <a class="local" href="pud-faq.html">pud-faq</a> for output in either <i>troff</i>
(groff, nroff) or html. The former can be viewed in a terminal via the UNIX
man page system, the latter can be viewed in a browser.</p>
<p class="default L50" style="margin-bottom:0">
The
<a class="local" href="pud-faq.html">PUD FAQ mini-language</a>
is described as a rather trivial FAQ itself. It can be viewed in
<a class="local" href="pud-faq.ps">PostScript</a>
(compiled from troff compiled from
<a class="local" href="pud-faq.azm">the zoem source</a>
and in
<a class="local" href="pud-faq.txt">plain text</a>
(again compiled from troff).</p>
<p class="default L50" style="margin-bottom:0">
For examples behold the
<a class="extern" href="http://micans.org/mcl/man/mclfaq.html">browsing delight</a>
that is the mcl FAQ, and the
<a class="extern" href="http://micans.org/mcl/man/mclfaq.ps">PostScript pleasure</a>.
Find the
<a class="extern" href="http://micans.org/mcl/man/mclfaq.txt">noblest format</a>, the
<a class="extern" href="http://micans.org/mcl/man/mclfaq.7">impregnable troff</a>, and the
<a class="extern" href="http://micans.org/mcl/man/mclfaq.azm">source</a> for all that jazz.</p>

<a name="elsewhere"></a>
<h2>Manuals and FAQ examples elsewhere</h2>
<p class="default L50" style="margin-bottom:0">
<b>Other people</b> exist writing PUD. Not many yet.
Joost van Baal has used the pud-faq package and the pud-man package
to create documentation for
<a class="extern" href="http://mdcc.cx/gnupg/">GnuPG (in Dutch)</a>,
<a class="extern" href="http://mdcc.cx/pub/caspar/caspar-latest/doc/">caspar</a>,
and the
<a class="extern" href="http://mdcc.cx/pub/uruk/uruk-latest/man/">strong (fire)walls of uruk</a>.
The links point to directory listings; the zoem source files have
<tt>.azm</tt> suffixes. The Makefile(.am) files might be of interest as well.</p>

<a name="dch"></a>
<h2>DocBook considered harmful</h2>
<p class="default L50" style="margin-bottom:0">
People justly wonder why PUD turns away from the blazing light of
goodness that is DocBook. DocBook does provide manual page elements and
it does support gazillions of output devices.
Nevertheless DocBook man pages are a cruelty, a curse
and the bane of all things good and pure.</p>
<p class="default L50" style="margin-bottom:0">
DocBook cannot be written, it cannot be maintained, it cannot be
programmed. Yes, XML and DocBook are not <i>supposed</i> to be
programmed, but where is the decree that man should toil and suffer so
that his documentation would be transmogrifyable into all eternity?</p>
<p class="default L50" style="margin-bottom:0">
DocBook provides some sort of manual page ontology, describing
supposedly every element you might ever need. Inevitably you will
want to do things that are not provided and then you are stuck.
DocBook lists and enumerations are painful and limited. The verbosity
of DocBook makes a mountain out of what should be a mole hill.</p>
<p class="default L50" style="margin-bottom:0">
Zoem manual pages are concise and can be easily cross-referenced. The
source is a pleasure to read and output from self-documenting commands can
be imported. Zoem IO, macro and programming facilities make the
source extendable so that new requirements can be coped with.</p>
<p class="default L50" style="margin-bottom:0">
Wise people argue that one cannot fathom the needs of future generations and
urge the good people of UNIX to use DocBook. The fool knows that this
particular premise disproves the thesis and that joy begets joy.
Factor the present into the authoring sustainability equation and the
scales tip.</p>
<p class="default L50" style="margin-bottom:0">
At this juncture, I am hesitantly willing to bet that the PUD languages
can easily be ported to DocBook. None of the pain, all of the gain.
The PUD <i>itemize</i> environment is a sticking point though. It
provides, horrors, a few formatting options. Optional paragraphs skips,
compact mode, right-alignment of items, automatic enumeration, and the
fantabulous intermezzo feature.</p>

<a name="info"></a>
<h2>Info evil</h2>
<p class="default L50" style="margin-bottom:0">
The good people of info consider manual pages obsolete. What
more is there to say? It is all written
<a class="extern" href="http://micans.org/stijn/views/infoinferno.html">here</a>.</p>

<a name="author"></a>
<h2>AUTHOR</h2>
<p class="default L50" style="margin-bottom:0">PUD was written by Stijn van Dongen.</p>

<a name="seealso"></a>
<h2>SEE ALSO</h2>
<div style="margin-top:1em">
<table
cellspacing="0" border=0
cellpadding="0" summary="itemize">
<tr><td width=32 valign="top" class="left nowrap"><a class="local" href="pud-man.html">pud-man</a></td><td width=8>&nbsp;</td><td><div style="text-align:justify"> &nbsp;
</div></td></tr><tr><td width=32 valign="top" class="left nowrap"><a class="local" href="pud-faq.html">pud-faq</a></td><td width=8>&nbsp;</td><td><div style="text-align:justify"> &nbsp;
</div></td></tr><tr><td width=32 valign="top" class="left nowrap"><a class="local" href="pud-base.html">pud-base</a></td><td width=8>&nbsp;</td><td><div style="text-align:justify"> &nbsp;
</div></td></tr><tr><td width=32 valign="top" class="left nowrap"><a class="local" href="pud-ref.html">pud-ref</a></td><td width=8>&nbsp;</td><td><div style="text-align:justify"> &nbsp;
</div></td></tr>
</table>

</div>
</body>
</html>