v0.1, 2002-09-07
Wijzigingen | ||
---|---|---|
Herziening 0.1 | 2002-09-07 | Herzien 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.
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:
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?
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.
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.
Volgende | ||
Hoe worden manpages benaderd? |