Nästan alla verktyg och projekt i Linux har välskrivna manualsidor. Det är något vi tar för givet i Linux. Samtidigt kan det verka som något mystiskt med hur manualsidor är uppbyggda.

Det är därför tid att vi lär oss hur man skriver, formaterar och installerar manualsidor, så att även du och jag kan inkludera manualsidor i vårt nästa projekt.

Som exempel kommer jag här att skriva en manualsida för subnetcalc, en mycket enkel subnet-kalkylator jag skrev för några år sedan. Den har dock alltid saknat en manualsida – något vi nu ska råda bot på.

Manualsidorna är formaterade i ett språk som kallas troff, och daterar ända tillbaks till 1970-talet. Det ett markup-språk som exempelvis LaTeX, HTML eller Markdown, om än mycket äldre.

Den kompletta manualsidan för subnetcalc ser ut som nedan.

.TH SUBNETCALC 1 "OCTOBER 2020" "Version 1" "User Manuals"
.SH NAME
subnetcalc \- calculate the number of address in a subnet
.SH SYNOPSIS
.B subnetcalc \fR[netmask] [-s]
.SH DESCRIPTION
.B subnetcalc
is a simple subnet calculator. The user provides a subnet to the program,
either as a argument or interactivly. The program then calculates the total
number of addresses and usable addresses in that subnet. It is also possible to
do batch processing with \fB\-s\fR option.
.SH OPTIONS
.TP
.BR \-s
Makes the program silent and accept input on stdin. In this mode, the program
will only calculate the total number of addresses in the given netmask.
.SH RETURN VALUES
Upon error, 1 is returned. Otherwise, 0 is returned.
.SH AUTHOR
Jack-Benny Persson <jack-benny@cyberinfo.se>
.SH "SEE ALSO"
.BR bc (1)

Ovanstående kod sparas i en fil, subnetcalc.1. Ettan indikerar att detta är ett användarkommando (sektion 1 i manualen). Vi kan testa att öppna manualsidan även när den ligger i exempelvis hemkatalogen.

$> man ./subnetcalc.1

Resultatet visas i nedanstående bild.

Troff

Det mesta av formateringen i troff görs med kommandon som börjar med en punkt på en ny rad.

Det första exemplet i manualsidan ovan är .TH som är titeln på manualsidan. Jämför texten som står efter .TH med resultatet i bilden ovan. Lägg märke till hur datumet och versionen visas i sidfoten, men SUBNETCALC(1) och User Manuals i sidhuvudet.

Därefter har vi .SH NAME, där .SH står för Section Header. NAME är styckets namn. I manualsidorna skriver vi alla styckerubriker med versaler. All text som kommer under .SH NAME är en del av det stycket. Lägg också märke till att vi escapar bindestrecket med \-.

Nästa styckerubrik är SYNOPSIS. Denna delen ska ge ett snabb översikt över hur programmet används. Här har vi .B subnetcalc \fR[netmask] [-s]. Den första formateringen här är .B för bold, alltså fetstil. Därefter återgår vi till normal text med \fR där \f står för font och är ett sätt att ändra stilen på samma rad. R står för regular, alltså vanlig text.

Nästa styckerubrik är DESCRIPTION som är en mer utförlig beskrivning av programmet. Här använder jag .B för att göra ordet subnetcalc i fetstil. Texten på nästkommande rader återgår automatiskt till vanlig stil.

Nästa styckerubrik är OPTIONS. Här listar vi alla flaggor programmet kan ta. Notera att vi här använder en indenterad lista. Detta åstadkoms med .TP som fixar till en snygg lista helt automatiskt. Första flaggan är listan är -s. Flaggan fetmarkeras med .B \-s. Det som sedan följer på nästkommande rader blir indenterade i manualsidan (se bilden). Resultatet blir en prydligt formaterad lista.

Därefter följer ytterligare tre styckerubriker, RETURN VALUES, AUTHOR och SEE ALSO. Dessa är formaterade precis som övriga stycken. Däremot under SEE ALSO har vi formaterat bc(1) med .BR bc (1). B står för bold och R för regular, vilket vi redan lärt oss. Men när man kombinerar dem kommer det första ordet bli fetmarkerat – bc i det här fallet – och efterföljande ord formateras med vanlig text, alltså (1) i vårt fall.

Installera manualsidan i systemet

Att installera en manualsida i systemet är inte svårare än att gzippa filen och placera den i rätt katalog.

$> gzip subnetcalc.1
$> sudo install -g root -o root -m 0644 subnetcalc.1.gz \ 
> /usr/share/man/man1/

Första kommandot skapar en gzippad fil av manualsidan. Filnamnet blir subnetcalc.1.gz.

I det andra kommandot installerar vi manualsidan i systemet som root. Det hade även gått att kopiera eller flytta filen till rätt katalog med cp eller mv, men install har fördelen att man kan sätta ägare, grupp och rättigheter direkt.

Katalogen vi placerar manualsidan i är /usr/share/man/man1/. Den katalogen innehåller manualsidor för alla användarkommandon. Andra kataloger är /usr/share/man/man2 som innehåller manualsidor för systemanrop. Katalogen /usr/share/man/man3 innehåller manualsidor för standardbibliotekets funktioner. Siffran på slutet av katalogens namn representerar manualens sektion. Detsamma gäller ettan i filnamnet subnetcalc.1.gz. Detsamma gäller även ettan inom parentesen i rubriken på manualsidan. Du hittar en komplett lista över manualens samtliga sektioner med man man.

Nu när manualsidan är installerad kan vi läsa den med man 1 subnetcalc, eller bara man subnetcalc.

Andra styckerubriker

De styckerubriker vi använt i denna manualsidan är att anse som ett minimum. Andra styckerubriker som är att ta med är BUGS, COPYRIGHT och REPORTING BUGS.