<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<article>
<articleinfo>
    <title>Linux Man Page Howto</title>
    <author>
        <firstname> Jens </firstname>
        <surname> Schweikhardt</surname>
        <affiliation>
        <address><email>howto@schweikhardt.net</email></address>
        </affiliation>
    </author>
<author>
<firstname> Vertaald door: Ellen</firstname>
<surname> Bokhorst</surname>
<affiliation>
<address><email>bokkie@nl.linux.org</email></address>
</affiliation>
</author>


    <othercredit role='converter'>
    <firstname>Pradeep</firstname>
    <surname>Padala</surname>
    <contrib>Conversie van HTML naar DocBook v4.1.</contrib>
    </othercredit>
    <revhistory>

    <revision>
        <revnumber>0.1</revnumber>
        <date>2002-09-07</date>
        <authorinitials>ppadala</authorinitials>
        <revremark>Conversie van HTML naar Docbook v4.1
        </revremark>
    </revision>
    </revhistory>

    <pubdate>v0.1, 2002-09-07</pubdate>
    <abstract>
    <para>$Id: Man-Page-NL.sgml,v 1.1.1.1 2004/03/21 21:02:25 cor Exp $</para>
    <para>
    <emphasis>
In deze HOWTO wordt uitgelegd wat je in gedachten moet houden wanneer je
on-line documentatie gaat schrijven, een zogenoemde manpage, die je 
toegankelijk wilt maken via de opdracht <literal>man</literal>(1).
In dit document wordt naar een manual entry simpelweg gerefereerd als
een manpage, ongeacht de werkelijke lengte en zonder sexistische bedoelingen.
    </emphasis>
    </para>
    </abstract>
</articleinfo>

<sect1 id="q1"><title>Een paar gedachten over documentatie</title>

<para>Waarom schrijven we documentatie? Domme vraag. Omdat we willen dat
anderen ons programma, onze bibliotheekfunctie of wat we dan ook hebben 
geschreven en beschikbaar hebben gemaakt kunnen gebruiken. Maar het
schrijven van de documentatie is nog niet alles:
</para>

<itemizedlist>
<listitem>
<para>Documentatie moet toegankelijk zijn. Als het op een of andere
niet standaard lokatie is verborgen waar de aan documentatie gerelateerde
tools het niet kunnen vinden, hoe kan het dan zijn doel dienen?
</para>
</listitem>

<listitem>
<para>Documentatie moet betrouwbaar en accuraat zijn. Er is niets
ergerlijker dan het niet met elkaar overeenkomen van het functioneren
van het programma en de beschrijving van de documentatie. Gebruikers
zullen je vervloeken, je hatelijke mail sturen en je werk de prullenbak
in werpen, met de vastbesloten bedoeling nooit meer iets geschreven
door die stommeling te installeren.
</para>
</listitem>
</itemizedlist>

<para>De historische en welbekende wijze om onder UNIX documentatie
te benaderen is via de opdracht man(1). In deze HOWTO is beschreven
wat je moet doen om een manpage te schrijven die correct door de
aan documentatie gerelateerde tools wordt verwerkt. De belangrijkste
tools hiervan zijn <literal>man</literal>(1), <literal>xman</literal>(1x),
<literal>apropos</literal>(1), <literal>makewhatis</literal>(8) en
<literal>catman</literal>(8). De betrouwbaarheid en accuraatheid van
de informatie is natuurlijk geheel aan jou. Maar zelfs dit in
aanmerking genomen zul je hieronder 
<link linkend="q9">een aantal idee&euml;n</link> aantreffen die je
helpen een aantal valkuilen te voorkomen.
</para>
</sect1>

<sect1 id="q2"><title>Hoe worden manpages benaderd?</title>

<para>Je moet bekend zijn met het precieze mechanisme voor het benaderen
van manpages om aan je manpage de juiste naam toe te kennen en het op de
juiste lokatie te installeren. Elke manpage moet in een specifieke
sectie worden gecatalogiseerd, welke wordt aangeduid door een enkel teken.
De meest gebruikelijke secties en de voor mensen leesbare namen zijn onder
Linux:
</para>

<programlisting>
Sectie  De voor mensen leesbare naam
   1    Gebruikersopdrachten die door iedereen kunnen worden opgestart
   2    Systeemaanroepen, d.w.z. functies waarin voorzien door de kernel.
   3    Subroutines, d.w.z. libraryfuncties.
   4    Devices, d.w.z., speciale bestanden in de directory /dev.
   5    Beschrijvingen van bestandsformaten, b.v. /etc/passwd.
   6    Spellen, spreekt voor zich.
   7    Diversen, b.v. macropackages, conventies.
   8    Systeembeheertools die alleen root kan uitvoeren.
   9    Een andere (Linux specifieke) plaats voor documentatie over kernelroutines.
   n    (Afgekeurd) Nieuwe documentatie, die kan worden verplaatst naar een
        beter geschikte sectie.
   o    (Afgekeurd) Oude documentatie, die voor een gepaste periode kan worden
        behouden.
   l    (Afgekeurd) Lokale documentatie refererend naar dit specifieke systeem.
</programlisting>

<para>De naam van het bronbestand van de manpage (de invoer voor het
opmaaksysteem) is de naam van de opdracht, functie of bestandsnaam,
gevolgd door een punt, gevolgd door het teken van de sectie.
Als je documentatie schrijft over de opmaak van het bestand passwd&#39; 
dan noem je het bronbestand `passwd.5&#39;. Hier hebben we ook een
voorbeeld van een bestandsnaam die hetzelfde is als een opdrachtnaam.
Het kan zijn dat er zelfs een library subroutine is met de naam passwd.
De gebruikelijke wijze om deze dubbelzinnigheden op te lossen is het
onderverdelen in secties: De opdrachtbeschrijving is
te vinden in het bestand `passwd.1&#39; en de hypothetische library
subroutine in `passwd.3&#39;.</para>

<para>Soms worden extra tekens toegevoegd en krijg je bijvoorbeeld een
bestandsnaam als `xterm.1x&#39; of `wish.1tk&#39;. De 
bedoeling hiervan is aan te geven dat dit documentatie is voor respectievelijk
een X Window programma of een Tk toepassing. Een aantal manual browsers
is in staat gebruik te maken van deze aanvullende informatie.
Bijvoorbeeld xman zal `xterm(x)&#39; en `wish(tk)&#39; gebruiken in de 
lijst met beschikbare documentatie.
</para>


<para>Maak alsjeblieft geen gebruik van de secties n, o en l; volgens de
File System Standard zijn deze secties afgekeurd. Houd je aan 
de numerieke secties. Wees je bewust van naamsaanvaringen met bestaande
programma's, functies of bestandsnamen. Het is beslist geen goed idee om
nog een andere editor te schrijven en het ed, sed (voor smart ed) of
red (voor Rocky&#39;s ed) te noemen. Door ervoor te zorgen dat de naam
van je programma uniek is, voorkom je dat iemand jouw programma uitvoert
en de manpage van iemand anders leest, of andersom.
</para>

<para>Nu weten we in ieder geval welke naam we ons bestand moeten geven.
De volgende beslissing die moet worden genomen is de directory waarin het
uiteindelijk zal worden ge&iuml;nstalleerd (stel wanneer de gebruiker
`<literal>make install</literal>&#39; toepast op je package.)
Onder Linux staan alle manpages onder directory's die zijn weergegeven in
de omgevingsvariabele MANPATH. De aan documentatie gerelateerde tools
gebruiken MANPATH op dezelfde wijze als de shell PATH gebruikt om
uitvoerbare bestanden te lokaliseren. In feite heeft MANPATH hetzelfde
formaat als PATH. Elk bevat een door dubbele punten gescheiden lijst
met directory's (met als uitzondering dat MANPATH geen lege velden en
relatieve padnamen toestaat, het maakt alleen gebruik van absolute
namen). 

Als MANPATH niet is ingesteld of ge&euml;xporteerd, dan zal een standaardwaarde
worden gebruikt waarin op z'n minst de directory /usr/man is opgenomen.
Voor het versnellen van het zoeken en het klein houden van directory's bevatten
de directory's gespecificeerd door MANPATH (de zogenoemde basisdirectory's)
een boel subdirectory's met de naam `man&lt;s&gt;&#39; waarbij
&lt;s&gt; staat voor de sectietoekenning van &eacute;&eacute;n teken
ge&iuml;ntroduceerd in <link linkend="q2">bovenstaande tabel</link>. 
Het kan zijn dat niet alle secties worden voorgesteld door een subdirectory
omdat er simpelweg geen reden is om een lege `mano&#39; subdirectory bij
te houden.

Er kunnen echter directory's voorkomen met de namen `cat&lt;s&gt;&#39;,
`dvi&lt;s&gt;&#39; en `ps&lt;s&gt;&#39; waarin documentatie wordt
bewaard die klaar is voor de weergave of om af te drukken. Hierover later
meer. Het enige andere bestand in een basisdirectory zou een bestand met
de naam `whatis&#39; mogen zijn. Het doel en de aanmaak van dit bestand
zal ook in <link linkend="q12">paragraaf 12)</link> worden beschreven.
De veiligste wijze om een manpage voor sectie &lt;s&gt; op de juiste lokatie
te hebben ge&iuml;nstalleerd, is door het te plaatsen in de directory
/usr/man/man&lt;s&gt;. Een goede <literal>Makefile</literal>, echter,
zal de mogelijkheid bieden  dat de gebruiker een basisdirectory kan kiezen,
door middel van een <literal>make</literal> variabele, zoals bijvoorbeeld 
MANDIR. De meeste GNU-packages kunnen worden geconfigureerd met de optie 
<literal>--prefix=/wat/dan-ook</literal>. De manpages zullen dan onder
de basisdirectory /wat/dan-ook/man worden ge&iuml;nstalleerd.
Ik raad je aan in iets vergelijkbaars te voorzien.</para>

<para>Met de komst van de Linux File System Standard (FS-Stnd), 
werd 't allemaal wat gecompliceerder. [Noot: de FS-Stnd schijnt te worden
vervangen door de <ulink url="http://www.pathname.com/fhs/">Filesystem Hierarchy
Standard</ulink>, FHS.] De FS-Stnd 1.2 zet uiteen dat</para>

<para>&quot;Voorzieningen moeten worden getroffen in de structuur van /usr/man
ter ondersteuning van manpages geschreven in andere (of meerdere) talen.&quot;
</para>

<para>Dit wordt bewerkstelligd door het introduceren van een ander
directoryniveau welk onderscheid maakt tussen de verschillende talen.
Nogmaals de FS-Stnd 1.2 aanhalend:
</para>

<para>&quot;Deze benoeming van taalsubdirectory's van /usr/man is
gebaseerd op Appendix E van de POSIX 1003.1 standaard waarin de locale
identificatiestring wordt beschreven, de best geaccepteerde methode om
een culturele omgeving te beschrijven. De &lt;locale&gt; string is:
&lt;taal&gt;[_&lt;gebied&gt;][.&lt;tekenset&gt;][,&lt;versie&gt;]&quot;</para>


<para>(Zie de FS-Stnd voor een paar algemene &lt;locale&gt; strings.)
Overeenkomstig deze richtlijnen staan onze manpages onder
/usr/man/&lt;locale&gt;/man[1-9lno]. De opgemaakte versies staan dan
natuurlijk in /usr/man/&lt;locale&gt;/cat[1-9lno], anders zouden we
ze alleen voor een enkele locale kunnen leveren. Ik kan je ECHTER thans niet
aanbevelen naar die structuur over te schakelen.
De FS-Stnd 1.2 staat ook toe dat</para>

<para>&quot;Systemen die een unieke taal en codeset voor alle
manpages instellen, mogen de &lt;locale&gt; substring achterwege laten
en alle manpages opslaan in &lt;mandir&gt;. Systemen met bijvoorbeeld
alleen Engelstalige manpages gecodeerd in ASCII, mogen manpages
(de <literal>man[1-9]</literal> directory's) direct opslaan in /usr/man.
(Dat is in feite de traditionele omstandigheid en regeling.)
&quot;</para>


<para>Ik zou niet overschakelen voordat alle tools (zoals xman, tkman, info
en vele anderen die manpages inlezen) met de nieuwe structuur overweg kunnen.
</para>
</sect1>

<sect1 id="q3"><title>Hoe hoort een opgemaakte manpage eruit te zien?</title>

<para>Laat me je een voorbeeld presenteren. Hieronder zal ik het in detail
uitleggen. Als je dit in gewone tekst leest, zal het de verschillende
lettertypen niet tonen (<emphasis>vet</emphasis> en
<emphasis>schuindruk</emphasis>). [TEDOEN: de nadruk en schuindruk
is verdwenen bij de conversie naar SGML/HTML; breng het terug.]
Raadpleeg alsjeblieft de paragraaf
&quot;<link linkend="q8">Wat zijn de fontconventies?</link>&quot; voor meer
uitleg. Hier is de manpage voor het (hypothetische)
<literal>foo</literal> programma.</para>

<programlisting>
FOO(1)                     Gebruikershandleidingen                    FOO(1)


NAAM
    foo - frobnicate de bar library

SYNTAX
    foo [-bar] [-c configuratiebestand ] bestand ...

BESCHRIJVING
     foo  frobnicates de bar library door interne symbooltabellen
     aan te passen. Standaard verwerkt het alle baz segmenten en 
     herschikt ze in omgekeerde tijdsvolgorde wil de xyzzy(1)
     linker ze kunnen vinden. De symdef entry wordt dan gecomprimeerd 
     gebruik makend van het WBG (Whiz-Bang-Gizmo) algoritme. Alle bestanden 
     worden in de opgegeven volgorde verwerkt.

OPTIES
     -b   Schrijf tijdens de verwerking geen `busy' meldingen naar stdout.

     -c configuratiebestand
          Gebruik het alternatieve systeemomvattende configuratiebestand 
          in plaats van /etc/foo.conf. Hiermee wordt de omgevingsvariabele
          FOOCONF overschreven.

     -a   Verwerk in aanvulling op de baz segmenten ook de blurfl headers.

     -r   Recursieve modus. Functioneert zo snel als het licht ten koste
          van een megabyte aan virtueel geheugen.

BESTANDEN
     /etc/foo.conf
          Het systeemomvattende configuratiebestand. Zie foo(5) voor
          meer details.
     ~/.foorc
          Configuratiebestand per gebruiker. Zie foo(5) voor meer
          details.

OMGEVING
     FOOCONF
          Als het een waarde bevat de volledige padnaam voor een
          alternatief systeemomvattend foo.conf. Wordt overschreven
          door de optie -c.

DIAGNOSE
     De volgende diagnoses kunnen op stderr worden uitgevoerd:

     Onjuist magisch nummer.
          Het invoerbestand lijkt niet op een archiefbestand.
     baz segmenten in oude stijl.
          foo kan alleen omgaan met baz segmenten in de nieuwe stijl. COBOL
          objectlibrary's worden in deze versie niet ondersteund.

BUGS
     De opdrachtnaam zou zorgvuldiger moeten zijn gekozen om zijn
     doel weer te geven.

AUTEUR
     Jens Schweikhardt <ulink url="mailto:howto@schweikhardt.net">&lt;howto at schweikhardt dot net&gt;</ulink>

ZIE OOK
     bar(1), foo(5), xyzzy(1)

Linux                Last change: MAART 1995                    2

</programlisting>

<para>Hier is de uitleg zoals ik beloofde.</para>

<para><emphasis>De sectie NAAM</emphasis></para>

<para>...is de enige vereiste sectie. Man pages zonder naamsectie
zijn zo bruikbaar als koelkasten op de noordpool. Deze sectie
heeft tevens een gestandaardiseerde opmaak bestaande uit een
door komma's gescheiden lijst met programma- of functienamen,
gevolgd door een koppelteken, gevolgd door een beknopte
(gewoonlijk bestaande uit een nregelige) beschrijving van de
functionaliteit die het programma (of de functie of het bestand)
wordt verondersteld te leveren. Door middel van
<literal>makewhatis</literal>(8), komen de naam secties terecht in
de <literal>whatis</literal> databasebestanden.
<literal>Makewhatis</literal> is de reden dat de naamsectie moet
voorkomen, en waarom het moet voldoen aan de hier beschreven opmaak.
In de <literal>groff</literal> broncode moet het er uitzien als</para>

<para><emphasis>.SH NAAM foo \- frobnicate de bar library</emphasis></para>

<para>De \- is hier van belang. De backslash is nodig om onderscheid
te kunnen maken tussen een koppelteken en een afbreekstreepje welk
in de opdrachtnaam of de nregelige beschrijving voor kan komen.
</para>

<para><emphasis>De sectie SYNTAX</emphasis></para>

<para>...is bedoeld voor een beknopt overzicht van beschikbare programma-opties.
Bij functies wordt in deze sectie een opsomming gegeven van corresponderende
include bestanden en het prototype zodat de programmeur het type en aantal
argumenten weet als ook het returntype.
</para>

<para><emphasis>De sectie BESCHRIJVING</emphasis></para>

<para>...legt welsprekend uit waarom je reeks nullen en &eacute;nen ook
maar iets waard is. Hier schrijf je al je kennis neer.
Dit is je reputatie. Win de bewondering van andere programmeurs en
gebruikers door van deze sectie de bron met betrouwbare en gedetailleerde
informatie te maken. Geef uitleg over waar de argumenten voor dienen, de
bestandsopmaak, welke algoritmen het vuile werk opknappen.
</para>

<para><emphasis>De sectie OPTIES</emphasis></para>

<para>...geeft een beschrijving van hoe elke optie het functioneren van
het programma benvloedt. Dat wist je al, nietwaar?
</para>

<para><emphasis>De sectie BESTANDEN</emphasis></para>

<para>...een opsomming van bestanden die het programma of de functie gebruikt.
Hier staan bijvoorbeeld configuratiebestanden, opstartbestanden en 
bestanden waar het programma op directe wijze bewerkingen op uitvoert.
Het is een goed plan om de volledige padnaam van deze bestanden te geven
en ervoor te zorgen dat het installatieproces het directory gedeelte
aanpast overeenkomstig de voorkeuren van de gebruiker:
de <literal>groff</literal> manpages hebben het standaardvoorvoegsel
/usr/local, dus refereren ze standaard naar /usr/local/lib/groff/* . 
Als je echter tijdens de installatie gebruik maakt van
&#39;make prefix=/opt/gnu&#39; dan veranderen de verwijzingen in de manpage
in /opt/gnu/lib/groff/*</para>

<para><emphasis>De sectie OMGEVING</emphasis></para>

<para>...geeft een opsomming van alle omgevingsvariabelen die van invloed
zijn op je programma of functie en vertelt uiteraard hoe. Het meest
gebruikelijk is dat de waarden van variabelen padnamen, bestandsnamen 
of standaardopties zijn.
</para>

<para><emphasis>De sectie DIAGNOSE</emphasis></para>

<para>...zou een overzicht moeten geven van de meest gebruikelijke
foutmeldingen van je programma en hoe hier mee om te gaan. Het is 
niet nodig om foutmeldingen van het systeem uit te leggen
(van <literal>perror</literal>(3)) of fatale signalen (van
<literal>psignal</literal>(3)) aangezien die tijdens de uitvoering
van elk programma plaats kunnen vinden.
</para>

<para><emphasis>De sectie FOUTEN</emphasis></para>

<para>...zou ideaal gezien niet bestaan. Als je flink bent, kun je
hier de beperkingen, bekende ongemakken en voorzieningen beschrijven
die anderen als onvoorzieningen kunnen beschouwen. Hernoem het tot
de TODO sectie als je niet zo flink bent ;-)
</para>

<para><emphasis>De sectie AUTEUR</emphasis></para>

<para>...is aardig als het er is voor het geval er grove fouten in de
documentatie of het functioneren van het programma voorkomen en je een
foutenrapport wilt mailen.
</para>

<para><emphasis>De sectie ZIE OOK</emphasis></para>

<para>...bestaat uit een lijst met gerelateerde manpages in alfabetische
volgorde. Conventioneel is het de laatste sectie.
Je bent er vrij in andere secties te bedenken als ze echt niet
in n van de secties die tot dusverre zijn beschreven passen.
Dus hoe precies genereerde je die manpage? Ik verwachtte die vraag,
hier is de broncode:
</para>

<programlisting>
.\&quot; Verwerk dit bestand met
.\&quot; groff -man -Tascii foo.1
.\&quot;
.TH FOO 1 &quot;MAART 1995&quot; Linux &quot;Gebruikershandleidingen&quot;
.SH NAAM
foo \- frobnicate de bar library
.SH SYNTAX
.B foo [-bar] [-c
.I configuratiebestand
.B ]
.I bestand
.B ...
.SH BESCHRIJVING
.B foo
frobnicates de bar library door interne symbooltabelen aan te passen.
Standaard verwerkt het alle baz segmenten
en herschikt ze in omgekeerde tijdsvolgorde zodat de
.BR xyzzy (1)
linker ze kan vinden. De symdef entry wordt dan gecomprimeerd
gebruik makend van het WBG (Whiz-Bang-Gizmo) algoritme.
Alle bestanden worden in de opgegeven volgorde verwerkt.
.SH OPTIES
.IP -b
Schrijf tijdens de verwerking geen `busy' meldingen naar stdout.
.IP &quot;-c configuratiebestand&quot;
Gebruik het alternatieve systeemomvattende
.I configuratiebestand
in plaats van
.IR /etc/foo.conf .
Dit overschrijft een
.B FOOCONF
omgevingsvariabele.
.IP -a
Verwerk in aanvulling op de baz segmenten ook de blurfl headers.
.IP -r
Recursieve modus. Functioneert zo snel als het licht
ten koste van een megabyte aan virtueel geheugen.
.SH BESTANDEN
.I /etc/foo.conf
.RS
Het systeemomvattende configuratiebestand. Zie
.BR foo (5)
voor meer details.
.RE
.I ~/.foorc
.RS
Configuratiebestand per gebruiker. Zie
.BR foo (5)
voor meer details.
.SH OMGEVING
.IP FOOCONF
Als het een waarde bevat de volledige padnaam voor een 
alternatief systeemomvattend
.IR foo.conf .
Wordt overschreven door de optie
.B -c .
.SH DIAGNOSE
De volgende diagnoses kunnen op stderr worden uitgevoerd:
 
Onjuist magisch nummer.
.RS
Het invoerbestand lijkt niet op een archiefbestand.
.RE
baz segmenten in oude stijl.
.RS
.B foo
kan alleen omgaan met baz segmenten in de nieuwe stijl. COBOL
objectlibrary's worden in deze versie niet ondersteund.
.SH BUGS
De opdrachtnaam zou zorgvuldiger moeten zijn gekozen
om zijn doel weer te geven.
.SH AUTEUR
Jens Schweikhardt &lt;howto at schweikhardt dot net&gt;
.SH &quot;ZIE OOK&quot;
.BR bar (1),
.BR foo (5),
.BR xyzzy (1)

</programlisting>
</sect1>

<sect1 id="q4"><title>Hoe documenteer ik verscheidene programma's/functies
in een enkele manpage?
</title>

<para>Veel programma's (<literal>grep</literal>,
<literal>egrep</literal>) en functies (<literal>printf</literal>,
<literal>fprintf</literal>, ...) zijn in een enkele manpage gedocumenteerd.
Deze manpages zouden echter tamelijk onbruikbaar zijn als ze slechts onder
&eacute;&eacute;n naam toegankelijk zouden zijn. We kunnen van een gebruiker
niet verwachten te onthouden dat de
<literal>egrep</literal> manpage in werkelijkheid de
<literal>grep</literal> manpage is. Daarom is het nodig de manpage onder
verschillende namen beschikbaar te stellen. Je hebt verschillende 
manieren om dit te bereiken:
</para>

<orderedlist>
<listitem>
<para>maak voor elke naam identieke kopie&euml;n.</para>
</listitem>

<listitem>
<para>verbind alle manpages met elkaar met behulp van hardlinks.</para>
</listitem>

<listitem>
<para>symbolische links verwijzend naar de feitelijke manpage.</para>
</listitem>

<listitem>
<para>gebruik het <literal>groff</literal>&#39;s `source&#39; mechanisme
geleverd door de <literal>.so</literal> macro.</para>
</listitem>
</orderedlist>

<para>De eerste manier is vanzelfsprekend een verspilling van diskruimte.
De tweede is niet aan te bevelen omdat intelligente versies van het
programma <literal>catman</literal> veel werk kunnen besparen door het
type bestand of de inhoud ervan te bekijken. <!-- Hardlinks will prevent
<literal>catman</literal> from being clever. -->(Het doel van 
<literal>catman</literal> is het formatteren van alle manpages zodat
ze snel kunnen worden weergegeven.) Het derde alternatief heeft een
klein nadeel: als flexibiliteit van belang is, dan moet je je er bewust
van zijn dat er bestandssystemen zijn die geen symbolische links ondersteunen.
Eind van het liedje is dat het 't beste is (TM) om gebruik te maken van
het sourcemechanisme van <literal>groff</literal>. Dat doe je zo:
Als je wilt dat je manpage in sectie 1 onder de namen `foo&#39; en `bar&#39;
beschikbaar is, dan plaats je de manpage in foo.1 en zorg je dat bar.1 er
als volgt uitziet:
</para>

<para><literal>.so man1/foo.1</literal></para>

<para>Het is van belang het <literal>man1/</literal> directory gedeelte
te specificeren als ook de bestandsnaam `foo.1&#39; omdat ten tijde dat
<literal>groff</literal> wordt uitgevoerd door de browser de basisdirectory
van de manpages de huidige werkdirectory zal zijn en 
<literal>groff</literal> interpreteert <literal>.so</literal>
argumenten relatief aan de huidige werkdirectory.</para>
</sect1>

<sect1 id="q5"><title>Welk macropackage kan ik het beste gebruiken?
</title>

<para>Er zijn een aantal macropackages speciaal ontworpen voor gebruik
bij het schrijven van manpages. Gewoonlijk zijn ze te vinden in de
groff macrodirectory /usr/lib/groff/tmac. De bestandsnamen zijn
<literal>tmac.</literal>&lt;iets&gt;, waarbij &lt;iets&gt;
het argument is aan de -m optie van groff. Groff zal
<literal>tmac.</literal>&lt;iets&gt; gebruiken wanneer het de optie
`<literal>-m</literal> &lt;iets&gt;&#39; meekrijgt. Vaak wordt de
spatie tussen `<literal>-m</literal>&#39; en
`&lt;iets&gt;&#39; weggelaten, dus kunnen we
zeggen `<literal>groff -man</literal>&#39; wanneer we manpages met
het macropackage <literal>tmac.an</literal> formatteren. 
Dat is de reden voor de vreemde naam `tmac.an&#39;. 
Afgezien van tmac.an is er nog een
ander populair macropackage, genaamd <literal>tmac.doc</literal>, welk
zijn oorsprong vindt op de Universiteit van Californi&euml; op Berkeley.
Veel BSD manpages gebruiken het en het schijnt dat UCB het tot standaard
heeft verheven voor documentatie. De
<literal>tmac.doc</literal> macro's zijn veel flexibeler, maar
helaas zijn er manpage browsers die ze niet zullen gebruiken
en altijd <literal>groff -man</literal> zullen aanroepen. Bijvoorbeeld alle
<literal>xman</literal> programma's die ik heb gezien zullen
manpages die <literal>tmac.doc</literal> nodig hebben verknallen.
Dus doe jezelf een plezier: gebruik <literal>tmac.an</literal> -- 
het gebruik van een ander macropackage wordt als schadelijk aangemerkt.
<literal>tmac.andoc</literal> is een
pseudo macropackage dat de broncode bekijkt en dan 
<literal>tmac.an</literal> of <literal>tmac.doc</literal> laadt.
In feite zou elke manpagebrowser het moeten gebruiken, maar tot op heden,
doen ze dit niet allemaal, dus is het 't beste als ons we vasthouden aan de oude
<literal>tmac.an</literal>. Alles wat ik je van nu af aan vertel 
met betrekking tot macro's geldt alleen voor <literal>tmac.an</literal>.
Als je toch gebruik wilt maken van de <literal>tmac.doc</literal> macro's,
bekijk dan de tutorialsampler, <ulink
url="http://www.freebsd.org/cgi/man.cgi?query=mdoc.samples"><literal>mdoc.samples</literal></ulink>.
Een aantal distro's (is me verteld) worden ook met mdoc(7), mdoc.samples(7) en
groff_man(7) geleverd.</para>

<para>De definitieve bron voor <literal>troff</literal>, waarin alle
macro's worden uitgelegd is de <emphasis>Troff User&#39;s Manual</emphasis>, 
beschikbaar in
<ulink url="http://cm.bell-labs.com/sys/doc/troff.html">html</ulink>,
<ulink url="http://cm.bell-labs.com/sys/doc/troff.ps">PostScript
(ps, 760K)</ulink> of
<ulink url="http://cm.bell-labs.com/sys/doc/troff.pdf">Portable
Document Format (pdf, 240K)</ulink>. door Jospeh F. Ossanna en Brian
W. Kernighan, gereviseerd November 1992. AT&amp;T Bell Labs heeft het voor
het publiek beschikbaar gesteld. Vergeet niet de laatste geweldige homepage
van <ulink url="http://www.kohala.com/start/">W. Richard Steven
</ulink> te bekijken (beroemd om <emphasis>Unix Network
Programming</emphasis> als ook de <emphasis>TCP/IP
Illustrated</emphasis> trilogie), die ook een lijst heeft met
<ulink url="http://www.kohala.com/start/troff/troff.html">Troff
Resources</ulink> waaronder <literal>tbl</literal>,
<literal>eqn</literal>, <literal>pic</literal> en andere
filters.</para>
</sect1>

<sect1 id="q6"><title>Welke preprocessors kan ik gebruiken?</title>

<para>Groff wordt op z'n minst met drie preprocessors geleverd,
<literal>tbl</literal>, <literal>eqn</literal>, en
<literal>pic</literal> (op een aantal systemen worden ze
<literal>gtbl</literal>, <literal>geqn</literal> en
<literal>gpic</literal> genoemd.) Hun doel is preprocessor macro's en hun data
om te zetten in reguliere troff invoer.
<literal>Tbl</literal> is een preprocessor voor tabellen,
<literal>eqn</literal> is een preprocessor voor vergelijkingen/berekeningen en
<literal>pic</literal> is een preprocessor voor afbeeldingen. Raadpleeg
alsjeblieft de manpages voor meer informatie over welke functionaliteit ze
leveren. In een notedop: schrijf geen manpages waarvoor een preprocessor
nodig is. Eqn zal gewoonlijk afschuwelijke uitvoer produceren voor
schrijfmachine-achtige devices, helaas het type device waarop 99% van alle
manpages worden bekeken (tenminste dat doe ik). Bijvoorbeeld
XAllocColor.3x maakt gebruik van een paar formules met machtsverheffen.
Vanwege de aard van schrijfmachine-achtige devices zal de exponent 
op dezelfde regel verschijnen als de basis.
N tot de macht van twee verschijnt als
`N2&#39;. <literal>Tbl</literal> kan maar beter worden vermeden omdat
alle xman programma's die ik heb gezien er op mislukken.
Xman 3.1.6 maakt gebruik van de volgende opdracht om manpages te
formatteren, b.v. signal(7):</para>

<para><literal>gtbl /usr/man/man7/signal.7 | geqn | gtbl | groff
-Tascii -man /tmp/xmana01760 2&gt; /dev/null</literal></para>

<para>wat bronnen verknalt waarin gebruik wordt gemaakt van 
<literal>gtbl</literal>, omdat de uitvoer van
<literal>gtbl</literal> weer als invoer wordt gegeven aan
<literal>gtbl</literal>. Het effect is een manpage zonder je tabel.
Ik weet niet of het een programmeerfout of een feature is dat
<literal>gtbl</literal> zich verslikt in zijn eigen uitvoer of dat xman
een beetje slimmer zou kunnen zijn door 
<literal>gtbl</literal> niet tweemaal te gebruiken.
Bovendien maakt een aantal systemen gebruik van <literal>grog</literal> 
om vast te stellen welke opties aan groff door te geven.
Helaas gist grog soms verkeerd en beveelt
<literal>groff -t</literal> aan wanneer in feite
<literal>tbl</literal> moet worden gebruikt. We blijven in feite met
twee oplossingen achter voor tabellen:
</para>

<orderedlist>
<listitem>
<para>Maak de tabel zelf handmatig op en plaats het tussen .nf en .fi
regels zodat het ongeformatteerd blijft. Je hebt op deze wijze geen
vet en schuindruk, maar je tabel wordt altijd maar weer geslikt.
</para>
</listitem>

<listitem>
<para>Gebruik de <literal>tbl</literal> macro's die je wilt, maar
distribueer de <literal>tbl</literal> uitvoer in plaats van de invoer.
Je hebt echter te maken met de eigenaardigheid van
<literal>grog</literal> die denkt dat een bestand met een regel
beginnend met <literal>.TS</literal> 
<literal>tbl</literal> vereist. <literal>Tbl</literal> uitvoer
bevat om voor mij onbekende reden nog steeds de
<literal>.TS</literal> en <literal>.TE</literal>. 
Het schijnt dat je ze simpelweg kunt verwijderen en dat het resultaat
er dan nog steeds ok uitziet. YMMV, dus test het alsjeblieft bij je
manpage.
</para>
</listitem>
</orderedlist>

<para>Ik moet nog een manpage te zien krijgen die de <literal>pic</literal>
preprocessing nodig heeft. Maar ik zou het niet prettig vinden. Zoals je
hierboven kunt zien, zal
<literal>xman</literal> het niet gebruiken en
<literal>groff</literal> zal beslist die fantastische gekkigheid op de invoer
toepassen.
</para>
</sect1>

<sect1 id="q7"><title>Moet ik broncode en/of reeds geformatteerde
documentatie distribueren?
</title>

<para>Laat me de voors (+) en tegens (-) geven van een paar uitgekozen
mogelijkheden:
</para>

<orderedlist>
<listitem>
<para>Alleen de broncode:+ kleiner distributiepackage.- ontoegankelijk op
systemen zonder <literal>groff</literal>.</para>
</listitem>

<listitem>
<para>Alleen ongecomprimeerd formaat:+ zelfs toegankelijk op systemen
zonder <literal>groff</literal>.- de gebruiker kan geen dvi of
postscript bestand genereren. - verspilling van diskruimte op systemen
die ook gecomprimeerde manpages hanteren.
</para>
</listitem>

<listitem>
<para>Alleen gecomprimeerd formaat:+ zelfs toegankelijk op systemen
zonder <literal>groff</literal>.- de gebruiker kan geen dvi of postscript
bestand genereren. - welk compressieformaat zou je gebruiken?
.Z? .z? .gz? Allemaal?</para>
</listitem>

<listitem>
<para>Broncode en ongecomprimeerd geformatteerd:+ toegankelijk zelfs op
systemen zonder <literal>groff</literal>.- groter distributie
package- een aantal systemen verwacht wellicht gecomprimeerde manpages.-
overtollige informatie op systemen uitgerust met
<literal>groff</literal>.</para>
</listitem>
</orderedlist>

<para>IMHO is het 't beste alleen de broncode te distribueren. Het argument
dat het ontoegankelijk is op systemen zonder <literal>groff</literal>
doet er niet toe. De 500+ manpages van het Linux Documentatie Project
bestaan alleen uit broncode. De manpages van XFree86 bestaan alleen uit
broncode. De manpages van de FSF bestaan alleen uit broncode.
In feite heb ik zelden software gezien die werd gedistribueerd met
geformatteerde manpages. Als een systeembeheerder het werkelijk belangrijk
vindt dat manpages toegankelijk zijn dan heeft hij ook
<literal>groff</literal> ge&iuml;nstalleerd.</para>
</sect1>

<sect1 id="q8"><title>Wat zijn de fontconventies?</title>

<para>Ten eerste: maak geen gebruik van directe fontoperators zoals
<literal>\fB</literal>, <literal>\fP</literal> enz. Gebruik macro's
die argumenten accepteren. Op deze wijze voorkom je een 
gebruikelijke valkuil: het wijzigen van het font aan het einde van
het woord en dat de vette tekst of schuindruk tot aan de volgende
fontwijziging doorgaat. Geloof me, het gebeurt vaker dan je denkt.
De <literal>tmac.an</literal> macro's voorzien in de volgende lettertypen:
</para>

<para>.B Vet</para>

<para>.BI Vet afgewisseld met schuindruk</para>

<para>.BR Vet afgewisseld met Roman</para>

<para>.I Schuindruk</para>

<para>.IB Schuindruk afgewisseld met vet</para>

<para>.IR Schuindruk afgewisseld met Roman</para>

<para>.RB Roman afgewisseld met vet</para>

<para>.RI Roman afgewisseld met schuindruk</para>

<para>.SM Klein (9/10 geschaald van de reguliere grootte)</para>

<para>.SB Klein vet (<emphasis>niet</emphasis> klein afgewisseld
met vet)</para>


<para>X afgewisseld door Y betekent dat de oneven argumenten grafisch
worden gezet in X terwijl de even argumenten worden gezet in Y. Bijvoorbeeld
</para>

<para>.BI &quot;Arg 1 is Vet, &quot; &quot;Arg 2 is Schuindruk,
&quot; &quot;en Vet, &quot; &quot;en Schuindruk.&quot;</para>


<para>De dubbele aanhalingstekens zijn nodig om witruimte in een argument
op te kunnen nemen; zonder deze aanhalingstekens verschijnt er geen
witruimte tussen de afwisselende lettertypen. 
In feite hoef je de macro's voor afwisselende lettertypen alleen te gebruiken
in die gevallen waar je witruimte tussen lettertype wijzigingen 
<emphasis>wilt</emphasis> voorkomen. 
Tot zover wat beschikbaar is. Hieronder hoe je gebruik zou moeten maken
van de verschillende lettertypen:
(delen schaamteloos overgenomen uit man(7))</para>

<para>Alhoewel er in de UNIX-wereld veel willekeurige conventies bestaan
voor manpages, definieert het bestaan van verscheidene honderden
Linux specifieke manpages onze standaards: Bij functies worden de
argumenten altijd gespecificeerd in schuindruk, zelfs in de SYNTAX sectie,
waar de rest van de functie vet wordt afgedrukt:
</para>

<para>.BI &quot;mijnfunctie(int &quot; argc &quot;, char **&quot;
argv );</para>


<para>Bestandsnamen staan altijd in schuindruk, behalve in de sectie SYNTAX,
waarin opgenomen bestanden vet zijn afgedrukt. Dus je zou gebruik kunnen
maken van</para>

<para>.I /usr/include/stdio.h</para>


<para>en</para>

<para>.B #include &lt;stdio.h&gt;</para>


<para>Speciale macro's, die gewoonlijk in hoofdletters staan, worden 
vet afgedrukt:</para>

<para>.B MAXINT</para>


<para>Bij het nummeren van een lijst met foutcodes, staan de codes 
vet afgedrukt. Deze lijst maakt gewoonlijk als volgt gebruik van de macro .TP 
(paragraaf met hangende tag):
</para>

<para>.TP.B EBADF.I fd is geen geldige file descriptor..TP.B
EINVAL.I fd is ongeschikt als leesstof</para>


<para>Elke verwijzing naar een andere manpage (of naar het onderwerp van
de huidige manpage) is vet afgedrukt. Als het nummer van de manpage wordt
gegeven, dan is dit in roman, zonder spaties:
</para>

<para>.BR man (7)</para>


<para>Acroniemen zien er het beste uit wanneer ze typografisch worden gezet
in een klein lettertype. Dus is mijn aanbeveling
</para>

<para>.SM UNIX</para>

<para>.SM ASCII</para>

<para>.SM TAB</para>

<para>.SM NFS</para>

<para>.SM LALR(1)</para>
</sect1>

<sect1 id="q9"><title>Je manpage oppoetsen</title>

<para>Hieronder staan een aantal richtlijnen die de betrouwbaarheid,
leesbaarheid en &#39;vorming&#39; van je documentatie verbeteren.
</para>

<itemizedlist>
<listitem>
<para>Test voorbeelden om er zeker van te zijn dat ze werken 
(gebruik knippen en plakken om je shell de exacte bewoording uit de manpage
te geven).
Kopieer de uitvoer van je opdracht in je manpage, typ niet slechts in wat
je <emphasis>denkt</emphasis> dat je programma zal afdrukken.</para>
</listitem>

<listitem>
<para>Proeflees het, pas de spellingscontrole erop toe en laat iemand anders 
het lezen, vooral als Engels je moedertaal niet is. De HOWTO die je aan het
lezen bent heeft de laatste test doorstaan (speciale dank aan
Michael Miller voor een nogal heldhaftige bijdrage! Alle resterende
ruwe kantjes zijn geheel mijn fout). Extra vrijwilligers zijn altijd welkom.
</para>
</listitem>

<listitem>
<para>Test je manpage: Produceert <literal>groff</literal> foutmeldingen
wanneer je je manpage formatteert? Het is aardig als je de
<literal>groff</literal> opdrachtregel in een commentaarregel plaatst.
Produceert de opdracht
<literal>man</literal>(1) foutmeldingen wanneer je
<literal>man jeprog</literal> aanroept? Produceert het 't verwachte resultaat?
Zullen <literal>xman</literal>(1x) en
<literal>tkman</literal>(1tk) met je manpage overweg kunnen? XFree86 3.1
heeft xman 3.1.6 - X11R6, het zal proberen te decomprimeren met
<literal>gzip -c -d &lt; %s &gt; %s zcat &lt; %s &gt;
%s</literal></para>
</listitem>

<listitem>
<para>Zal <literal>makewhatis</literal>(8) de &eacute;&eacute;nregelige
beschrijving uit de NAAM sectie kunnen extraheren?
</para>
</listitem>

<listitem>
<para>Zet je manpage om in HTML opmaak met behulp van
<literal>rman</literal> van <ulink url="http://polyglotman.sourceforge.net/">
http://polyglotman.sourceforge.net/</ulink>, en bekijk het resultaat met een
set webbrowsers (netscape, mozilla, opera, lynx, ...) Controleer of de
kruisverwijzingen tussen je manpages als hyperlinks in de gegenereerde HTML
functioneren. Als er een website bestaat voor je softwarepackage, plaats
daar dan de manpages, en houd ze bijgewerkt.
</para>
</listitem>

<listitem>
<para>Het utility <literal>rman</literal> kan manpages ook omzetten naar
LaTeX, RTF, SGML en andere formaten; kijk deze na als je je manpages
in een boek of ander groot document wilt opnemen.
</para>
</listitem>

<listitem>
<para>Probeer je manpage om te zetten in HTML met behulp van
<literal>man2html</literal>, wat al sinds man-1.4 onderdeel uitmaakt
van het Linux man-package. Het <literal>man2html</literal> utility is een minder
grootse vertaler dan <literal>rman</literal>, maar vrijwel elke
Linux gebruiker heeft het al, dus het is het waard te zorgen dat
<literal>man2html</literal> zich niet verslikt in je manpage.</para>
</listitem>

</itemizedlist>
</sect1>

<sect1 id="q10"><title>Hoe krijg ik een gewoon manpage in tekstformaat
zonder al die ^H^'s ?</title>

<para>Kijk eens naar <literal>col</literal>(1), omdat
<literal>col</literal> backspacereeksen kan filteren. Gewoon voor het geval
je niet zo lang kan wachten:
</para>

<para><literal>funnyprompt$ groff -t -e -mandoc -Tascii manpage.1 |
col -bx &gt; manpage.txt</literal></para>

<para>De <literal>-t</literal> en <literal>-e</literal> switches
vertellen <literal>groff</literal> voor te verwerken met
<literal>tbl</literal> en <literal>eqn</literal>. Dit is overdreven
voor manpages waar geen voorbewerking voor nodig is, maar afgezien
van een paar verspilde CPU cycli kan het geen kwaad. Aan de andere
kant kan het wel kwaad geen <literal>-t</literal> toe te passen
wanneer het in feitelijk nodig is: de tabel wordt afschuwelijk opgemaakt.
Je kunt er zelfs achterkomen (nou ja, gissen is een beter woord) welke
opdracht nodig is om een bepaald <literal>groff</literal> document
(niet gewoon manpages) te formatteren door het aanroepen van:</para>

<para><programlisting>funnyprompt$ grog /usr/man/man7/signal.7
groff -t -man /usr/man/man7/signal.7</programlisting>
</para>

<para>&quot;Grog&quot; staat voor &quot;GROff Guess&quot;, en het doet
wat het zegt--gissen. Als het perfect zou zijn, dan zouden we geen opties
meer nodig hebben. Ik heb het onjuist zien gissen bij macropackages en
preprocessors. Hier is een door mij geschreven klein
perlscript dat de paginakoppen en voettekten kan verwijderen, je daarbij
een paar pagina's besparend (en moeder natuur een boom) bij het afdrukken
van lange en uitgebreide manpages. Bewaar het in een bestand met de naam
<literal>strip-headers</literal> &amp; chmod 755.</para>

<programlisting>
    #!/usr/bin/perl -wn
    #  laat het 't hele bestand in &eacute;&eacute;n keer inlezen:
    undef $/;
    #  verwijder eerste koptekst:
    s/^\n*.*\n+//;
    #  verwijder laastste voettekst:
    s/\n+.*\n+$/\n/g;
    #  verwijder pagina-overgangen:
    s/\n\n+[^ \t].*\n\n+(\S+).*\1\n\n+/\n/g;
    #  combineer twee of meer lege regels tot &eacute;&eacute;n lege regel:
    s/\n{3,}/\n\n/g;
    #  bekijk wat er over is...
    print;
</programlisting>

<para>Je moet het als het eerste filter gebruiken na de opdracht
<literal>man</literal> aangezien het terugvalt op het aantal newlines
dat door <literal>groff</literal> wordt uitgevoerd.
Bijvoorbeeld:</para>

<para><literal>funnyprompt$ man bash | strip-headers | col -bx &gt;
bash.txt</literal></para>
</sect1>

<sect1 id="q11"><title>Hoe krijg ik een PostScript manpage van hoge kwaliteit?
</title>

<para><literal>funnyprompt$ groff -t -e -mandoc -Tps manpage.1 &gt;
manpage.ps</literal></para>

<para>Druk dat af of bekijk het met je favoriete PostScript printer/viewer.
Zie <link linkend="q10">vraag 10)</link> voor een uitleg
van de opties.
</para>
</sect1>

<sect1 id="q12"><title>Hoe krijg ik `apropos&#39; en `whatis&#39; werkend?</title>

<para>Stel dat je je afvraagt welke compilers op je systeem zijn
ge&iuml;nstalleerd en hoe deze kunnen worden aangeroepen.
Om deze (veelgestelde vraag) te beantwoorden, geef je op</para>

<programlisting>
funnyprompt$ apropos compiler
f77 (1) - Fortran 77 compiler 
gcc (1) - GNU C and C++ compiler
pc (1) - Pascal compiler
</programlisting>

<para><literal>Apropos</literal> en <literal>whatis</literal> worden gebruikt
om snel te rapporteren welke manpage informatie bevat over een bepaald
onderwerp. Beide programma's doorzoeken een aantal bestanden met de naam
`whatis&#39; die is te vinden in elk van de basisdirectory's van de manpages.
Zoals eerder uiteengezet, bevatten de whatis databasebestanden een
&eacute;&eacute;nregelige ingang voor elke manpage in de respectieve
directorystructuur. In feite is die regel exact gelijk aan de sectie NAAM 
(om precies te zijn: samengevoegd op &eacute;&eacute;n regel waarbij 
het verbindingsteken is verwijderd; de sectie wordt tussen haakjes vermeld).
De whatis databasebestanden worden
aangemaakt met het programma <literal>makewhatis</literal>(8). Er zijn
verscheidene versies in omloop, dus raadpleeg alsblieft de manpage om
vast te stellen welke opties beschikbaar zijn. Wil
<literal>makewhatis</literal> de NAAM secties correct kunnen extraheren
dan is het van belang dat jij, de schrijver van de manpage,
je houdt aan de opmaak van de NAAM sectie zoals beschreven onder
<link linkend="q3">vraag 3)</link>. De verschillen tussen
<literal>apropos</literal> en <literal>whatis</literal> zijn simpelweg
waar in de regel ze kijken, en waar ze naar zoeken.
<literal>Apropos</literal> (wat equivalent is aan <literal>man
-k</literal>) doorzoekt de argumentstring overal op de regel,
terwijl <literal>whatis</literal> (equivalent aan <literal>man
-f</literal>) een volledige opdrachtnaam alleen in dat deel voor het
streepje probeert te matchen. Als consequentie zal
`<literal>whatis cc</literal>&#39; het rapporteren als er een
<literal>cc</literal> manpage is en stil blijven voor <literal>gcc</literal>.
</para>

<para>Correcties en suggesties welkom!</para>
</sect1>

<sect1 id="copying"><title>Kopieervoorwaarden</title>

<para>Copyright 1995-2001 by Jens Schweikhardt. All rights
reserved.</para>

<programlisting>
 &quot;Two clause&quot; BSD License:

 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
 are met:
 1. Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.
 2. Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.

 THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS&#39;&#39; AND ANY EXPRESS OR
 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
 IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 POSSIBILITY OF SUCH DAMAGE.
</programlisting>
</sect1>

<sect1 id="acknowledgements"><title>Erkenningen</title>

<itemizedlist>
<listitem>
<para>Michael Miller voor het proeflezen van de volledige HOWTO (in februari
2001); Gordon Torrie voor de vele behulpzame grammaticale opmerkingen
(in augustus 2001). Eventuele resterende grammaticale of stijlfouten 
zijn geheel mijn fout.
</para>
</listitem>

<listitem>
<para><ulink url="http://www.SuSE.de/">S.u.S.E. (.de)</ulink> (of
<ulink url="http://www.SuSE.com/">.com</ulink>) de enige distributeur
die me gratis kopie&euml;n van hun laatste product blijven sturen,
mijn werk als howto auteur erkennend.
</para>
</listitem>

<listitem>
<para>George B. Moody voor aanvullende suggesties hoe een manpage op te
poetsen.
</para>
</listitem>
</itemizedlist>

<para>Laat een bericht bij me achter als je naam hier ontbreekt.</para>
</sect1>

<sect1 id="changelog"><title>Changelog</title>

<itemizedlist>
<listitem>
<para>Maart 6 2001: HTML broncode doorstaat nu <literal>weblint
-pedantic</literal>. <link linkend="q6">Paragraph 6:</link> Toegevoegd
workarounds voor <literal>tbl</literal> screw-ups. Toegevoegd
<link linkend="acknowledgements">Erkenningen</link> en
<link linkend="changelog">Changelog</link>. RCS Id toegevoegd.</para>
</listitem>

<listitem>
<para>Augustus 9 2001: Howto geplaatst onder een twee clausule BSD
licentie.</para>
</listitem>

<listitem>
<para>Augustus 20 2001: Grammatica verbeterd. Gebruik een genummerde lijst
voor de inhoudsopgave.
</para>
</listitem>

<listitem>
<para>Oktober 28 2001: Referenties naar mdoc(7), mdoc.samples(7) en
groff_man(7) toegevoegd.</para>
</listitem>

<listitem>
<para>April 28 2002: Grammaticacorrectie.
</para>
</listitem>

<listitem>
<para>April 30 2002: Werkte de link bij naar de groff_mdoc BSD tutorial.</para>
</listitem>

<listitem>
<para>November 29 2002: Meer suggesties voor het oppoetsen van je manpage.</para>
</listitem>

<listitem>
<para>December 15 2002: Publiceer SGML afgeleid van HTML. Verwijderde dode link
naar LSM.
</para>
</listitem>

</itemizedlist>
</sect1>

</article>