Hoe worden manpages benaderd?

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:

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.

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' dan noem je het bronbestand `passwd.5'. 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' en de hypothetische library subroutine in `passwd.3'.

Soms worden extra tekens toegevoegd en krijg je bijvoorbeeld een bestandsnaam als `xterm.1x' of `wish.1tk'. 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)' en `wish(tk)' gebruiken in de lijst met beschikbare documentatie.

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'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.

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ïnstalleerd (stel wanneer de gebruiker `make install' 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ë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<s>' waarbij <s> staat voor de sectietoekenning van één teken geïntroduceerd in bovenstaande tabel. Het kan zijn dat niet alle secties worden voorgesteld door een subdirectory omdat er simpelweg geen reden is om een lege `mano' subdirectory bij te houden. Er kunnen echter directory's voorkomen met de namen `cat<s>', `dvi<s>' en `ps<s>' 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' mogen zijn. Het doel en de aanmaak van dit bestand zal ook in paragraaf 12) worden beschreven. De veiligste wijze om een manpage voor sectie <s> op de juiste lokatie te hebben geïnstalleerd, is door het te plaatsen in de directory /usr/man/man<s>. Een goede Makefile, echter, zal de mogelijkheid bieden dat de gebruiker een basisdirectory kan kiezen, door middel van een make variabele, zoals bijvoorbeeld MANDIR. De meeste GNU-packages kunnen worden geconfigureerd met de optie --prefix=/wat/dan-ook. De manpages zullen dan onder de basisdirectory /wat/dan-ook/man worden geïnstalleerd. Ik raad je aan in iets vergelijkbaars te voorzien.

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 Filesystem Hierarchy Standard, FHS.] De FS-Stnd 1.2 zet uiteen dat

"Voorzieningen moeten worden getroffen in de structuur van /usr/man ter ondersteuning van manpages geschreven in andere (of meerdere) talen."

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

"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 <locale> string is: <taal>[_<gebied>][.<tekenset>][,<versie>]"

(Zie de FS-Stnd voor een paar algemene <locale> strings.) Overeenkomstig deze richtlijnen staan onze manpages onder /usr/man/<locale>/man[1-9lno]. De opgemaakte versies staan dan natuurlijk in /usr/man/<locale>/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

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

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