Just some quick notes about writing man pages for a Linux based system.
So, let's jump in. We're going to write a short man page, we can later retrieve with the man command, eg man ourpage. Mine's called manhowto. We use good old vi to do it, so call it with
vi filenameThe content of my test file is as follows. It's very basic, but it do work, and can be called with man.
cat -n manhowto
1 .\" Manpage for manhowto.
2 .\" Contact This email address is being protected from spambots. You need JavaScript enabled to view it. med fejl og rettelser
3 .TH man 8 "Mandag 20-07-2020" "1.0" "manhowto man side"
4
5 .SH NAME
6
7 manhowto \- Tutorial omkring oprettelse af man sider
8
9 .SH SYNOPSIS
10
11 man manhowto, for at læse tutorialen og lære lidt om hvordan man opretter man pages.
12 Beskrivelser af filer kan findes under sektionen "files".
13
14 .SH DESCRIPTION
15
16 Dette er beskrivelses sektionen, hvor man kan komme med en længere beskrivelse af de muligheder der er.
17 Man kan også komme med en beskrivelse af programmet, eller hvad man nu har lyst til.
18
19 .SH OPTIONS
20
21 Angiver options, i det her tilfælde er der ingen.
22
23 .SH SEE ALSO
24
25 Sektion for at beskrive yderligere dekomentaion.
26
27 .SH BUGS
28
29 Bugs sektion, ikke nødvendigt.
30
31 .SH AUTHOR
32
33 NX <This email address is being protected from spambots. You need JavaScript enabled to view it.> - http://www.blackdragon.se
nx@xeon:~$
We need to set a header, and tell man what section we want to include or man page into. Man are using 9 sections, and they are :
Section Description
1 Executable shell commands
2 System calls (functions provided by the kernel)
3 Library calls (functions within program libraries)
4 Special files (usually found in /dev)
5 File formats and conventions eg /etc/passwd
6 Games
7 Miscellaneous (including macro packages and conventions), e.g. man(7), groff(7)
8 System administration commands (usually only for root)
9 Kernel routines [Non standard]In my example i've used section 8, system administrative commands. So look at line 3.
3 .TH man 8 "Mandag 20-07-2020" "1.0" "manhowto man side"
.TH says we want to define a header. Next we tell man we want to place it in Section 8, system admin commands, We give the date, version and a header. When we run man, we can do it like this :
man .\filenameman(8) manhowto man side man(8)
NAME
manhowto - Tutorial omkring oprettelse af man sider
SYNOPSIS
man manhowto, for at læse tutorialen og lære lidt om hvordan man opretter man pages. Beskrivelser af filer kan findes under sektionen
"files".
DESCRIPTION
Dette er beskrivelses sektionen, hvor man kan komme med en længere beskrivelse af de muligheder der er. Man kan også komme med en
beskrivelse af programmet, eller hvad man nu har lyst til.
OPTIONS
Angiver options, i det her tilfælde er der ingen.
SEE ALSO
Sektion for at beskrive yderligere dekomentaion.
BUGS
Bugs sektion, ikke nødvendigt.
AUTHOR
NX <This email address is being protected from spambots. You need JavaScript enabled to view it.> - http://www.blackdragon.se
1.0 Mandag 20-07-2020 This is my output, when run through man.
So, from this, we learn that .SH gives us a section in a man page. So using .SH NAME | SYNOPSIS | DESCRIPTION | OPTIONS | SEE ALSO | BUGS | AUTHOR, sets the options i've used in my example file.
We save the file and convert it to a gz file.
gzip -k manfileAfter that, we have to rename it to the right filename. So, for a man page belonging in section 8, it would be
cp manfile.gz manfile.8.gzThe last thing we do, is figure out where it belongs in /usr/share/man. This example goes in /usr/share/man/man8/manfile.8.gz
Thats it. For details try the command
man manHave fun :)