Linux Man Page Howto

Jens Schweikhardt

Vertaald door: Ellen Bokhorst

v0.1, 2002-09-07

Wijzigingen
Herziening 0.12002-09-07Herzien door: ppadala
Conversie van HTML naar Docbook v4.1

$Id: Man-Page-NL.sgml,v 1.1 2003/05/13 11:34:22 bokkie Exp $

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 man(1). In dit document wordt naar een manual entry simpelweg gerefereerd als een manpage, ongeacht de werkelijke lengte en zonder sexistische bedoelingen.


Inhoudsopgave
Een paar gedachten over documentatie
Hoe worden manpages benaderd?
Hoe hoort een opgemaakte manpage eruit te zien?
Hoe documenteer ik verscheidene programma's/functies in een enkele manpage?
Welk macropackage kan ik het beste gebruiken?
Welke preprocessors kan ik gebruiken?
Moet ik broncode en/of reeds geformatteerde documentatie distribueren?
Wat zijn de fontconventies?
Je manpage oppoetsen
Hoe krijg ik een gewoon manpage in tekstformaat zonder al die ^H^'s ?
Hoe krijg ik een PostScript manpage van hoge kwaliteit?
Hoe krijg ik `apropos' en `whatis' werkend?
Kopieervoorwaarden
Erkenningen
Changelog

Een paar gedachten over documentatie

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:

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 man(1), xman(1x), apropos(1), makewhatis(8) en catman(8). De betrouwbaarheid en accuraatheid van de informatie is natuurlijk geheel aan jou. Maar zelfs dit in aanmerking genomen zul je hieronder een aantal ideeën aantreffen die je helpen een aantal valkuilen te voorkomen.