Hoe hoort een opgemaakte manpage eruit te zien?

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)