Hoe documenteer ik verscheidene programma's/functies in een enkele manpage?

Veel programma's (grep, egrep) en functies (printf, fprintf, ...) zijn in een enkele manpage gedocumenteerd. Deze manpages zouden echter tamelijk onbruikbaar zijn als ze slechts onder één naam toegankelijk zouden zijn. We kunnen van een gebruiker niet verwachten te onthouden dat de egrep manpage in werkelijkheid de grep manpage is. Daarom is het nodig de manpage onder verschillende namen beschikbaar te stellen. Je hebt verschillende manieren om dit te bereiken:

  1. maak voor elke naam identieke kopieën.

  2. verbind alle manpages met elkaar met behulp van hardlinks.

  3. symbolische links verwijzend naar de feitelijke manpage.

  4. gebruik het groff's `source' mechanisme geleverd door de .so macro.

De eerste manier is vanzelfsprekend een verspilling van diskruimte. De tweede is niet aan te bevelen omdat intelligente versies van het programma catman veel werk kunnen besparen door het type bestand of de inhoud ervan te bekijken. (Het doel van catman is het formatteren van alle manpages zodat ze snel kunnen worden weergegeven.) Het derde alternatief heeft een klein nadeel: als flexibiliteit van belang is, dan moet je je er bewust van zijn dat er bestandssystemen zijn die geen symbolische links ondersteunen. Eind van het liedje is dat het 't beste is (TM) om gebruik te maken van het sourcemechanisme van groff. Dat doe je zo: Als je wilt dat je manpage in sectie 1 onder de namen `foo' en `bar' beschikbaar is, dan plaats je de manpage in foo.1 en zorg je dat bar.1 er als volgt uitziet:

.so man1/foo.1

Het is van belang het man1/ directory gedeelte te specificeren als ook de bestandsnaam `foo.1' omdat ten tijde dat groff wordt uitgevoerd door de browser de basisdirectory van de manpages de huidige werkdirectory zal zijn en groff interpreteert .so argumenten relatief aan de huidige werkdirectory.