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 (vet en schuindruk). [TEDOEN: de nadruk en schuindruk is verdwenen bij de conversie naar SGML/HTML; breng het terug.] Raadpleeg alsjeblieft de paragraaf "Wat zijn de fontconventies?" voor meer uitleg. Hier is de manpage voor het (hypothetische) foo programma.
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 <howto at schweikhardt dot net> ZIE OOK bar(1), foo(5), xyzzy(1) Linux Last change: MAART 1995 2 |
Hier is de uitleg zoals ik beloofde.
De sectie NAAM
...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 makewhatis(8), komen de naam secties terecht in de whatis databasebestanden. Makewhatis is de reden dat de naamsectie moet voorkomen, en waarom het moet voldoen aan de hier beschreven opmaak. In de groff broncode moet het er uitzien als
.SH NAAM foo \- frobnicate de bar library
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.
De sectie SYNTAX
...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.
De sectie BESCHRIJVING
...legt welsprekend uit waarom je reeks nullen en é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.
De sectie OPTIES
...geeft een beschrijving van hoe elke optie het functioneren van het programma beïnvloedt. Dat wist je al, nietwaar?
De sectie BESTANDEN
...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 groff manpages hebben het standaardvoorvoegsel /usr/local, dus refereren ze standaard naar /usr/local/lib/groff/* . Als je echter tijdens de installatie gebruik maakt van 'make prefix=/opt/gnu' dan veranderen de verwijzingen in de manpage in /opt/gnu/lib/groff/*
De sectie OMGEVING
...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.
De sectie DIAGNOSE
...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 perror(3)) of fatale signalen (van psignal(3)) aangezien die tijdens de uitvoering van elk programma plaats kunnen vinden.
De sectie FOUTEN
...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 ;-)
De sectie AUTEUR
...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.
De sectie ZIE OOK
...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:
.\" Verwerk dit bestand met .\" groff -man -Tascii foo.1 .\" .TH FOO 1 "MAART 1995" Linux "Gebruikershandleidingen" .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 "-c configuratiebestand" 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 <howto at schweikhardt dot net> .SH "ZIE OOK" .BR bar (1), .BR foo (5), .BR xyzzy (1) |