Při vývoji softwaru je nezbytně nutným aspektem dokumentace. Psaní dokumentace by mělo být samozřejmostí pro každý projekt a je důležitým měřítkem úspěchu. I velmi pěkně napsaná aplikace bez dokumentace může ztratit velkou část své hodnoty.

Nejpoužívanější způsob, jak v Unixu zdokumentovat aplikaci pro pokročilejší uživatele, je vytvoření manuálové stránky. Měla by obsahovat kompletní popis daného programu.

Členění manuálových stránek

Protože manuálových stránek existuje spousta, je zde snaha o nějaké členění. Můžeme je rozdělit do skupin, uvedených v tabulce:

Těchto osm sekcí existuje vždy. Tu a tam se objeví nějaká další, nestandardní. Některé sekce jsou dále dělené. Existuje tak například sekce 3pm pro moduly Perlu nebo 3qt pro knihovny Qt.

Prohlížení manuálových stránek

Přepínač --help

Přestože to s manuálovými stránkami přímo nesouvisí, mezi základní formy dokumentace patří přepínač --help. V případech, kdy potřebujeme k danému programu rychle zjistit nějakou informaci jako je přepínač, je nejlepší začít právě přidáním přepínače --help. Většina běžných příkazů ho podporuje. Pro rychlou informaci o přepínačích příkazu apropos stačí zadat:

$ apropos --help
Použití: apropos [-d] [-r|-w|-e] [-m systém] [-M cesta_k_manuálovým_stránkám] 
| [-h] | [-V] klíčové_slovo ...
-d, --debug                produce debugging info.
-r, --regex                interpret each keyword as a regex (default).
-e, --exact                search each keyword for exact match.
-w, --wildcard             the keyword(s) contain wildcards.
-m, --systems system       include alternate systems' man pages.
-M, --manpath path         set search path for manual pages to `path'.
-V, --version              show version.
-h, --help                 show this usage message.
$

Výstup se zpravidla skládá ze dvou částí. První z nich je název programu a stručný popis několika slovy. Následuje výčet nejběžněji používaných přepínačů. Někdy se může vyskytnout i podrobnější informace o příkazu, ale nikdy by neměly přesáhnout určitou mez (jedna strana už je opravdu dost). Za prvé --help slouží jako blesková nápověda a obsáhnutí manuálu není účelem a navíc přílišná rozsáhlost práci místo usnadnění naopak ztěžuje.

Příkazy pro prohlížení

Budeme potřebovat jediný příkaz, kterým je man. To je jeden z vůbec nejčastěji používaných příkazů v Unixu. Je základním příkazem pro prohlížení manuálových stránek. Jako argument dostává nejčastěji pouze název programu, jehož manuálovou stránku chceme zobrazit nebo přímo cestu k souboru manuálové stránky.

$ man mkdir

Chceme-li specifikovat sekci, ve které se má manuálová stránka hledat, přidáme její název před název programu. Díky tomu tak následující dva příkazy zobrazí jinou manuálovou stránku:

$ man locale
$ man 3pm locale

Ten první vypíše informace o systémovém příkazu locale ze sekce 1 a ten další vytiskne manuálovou stránku o locale pragmě z Perlu ze sekce 3pm. Pro změnu pořadí prohledávání sekcí je třeba nastavit proměnnou prostředí MANSECT.

Poznámka - pro postupné zobrazení všech dostupných manuálových stránek stejného jména lze použít příkaz

$ man -a locale

Manuálové stránky se zobrazují pomocí příkazu, uloženého v systémové proměnné PAGER, jímž je implicitně less. Pohybovat se v nich lze kurzorovými šipkami, klávesami PageUp, PageDown nebo mezerníkem. Režim vyhledávání se spustí klávesou lomítka. Prohlížení se ukončuje stiskem q.

Pokud chceme používat grep, je třeba zobrazit manuálovou stránku bez zvýraznění. K tomu postačí napojit ještě před grepem výstup na příkaz col.

$ man apropos | col -b | grep -C5 regexp

Hledání manuálových stránek

Manuálové stránky můžeme použít i v případech, kdy naopak nějaký příkaz sháníme. Lze hledat dvěma způsoby. Buď pomocí klíčových slov anebo vyhledáváním v názvu manuálové stránky.

Pro hledání v klíčových slovech se používá příkaz man -k nebo jeho lépe zapamatovatelné synonymum apropos. Jako argumenty se uvádí klíčová slova.

$ apropos python
pyhtmlizer (1)       - pretty-print Python source as HTML
python (1)           - an interpreted, interactive, object-oriented 
                       programming language
$

Příkaz man -f nebo-li whatis hledá pouze v názvech manuálových stránek.

$ whatis stdio
stdio (3)            - standard input/output library functions
$

Jak apropos, tak whatis podporují vyhledávání pomocí regulárních výrazů. Stačí jen přidat přepínač --regex.

Vyhledávat lze i umístění, kde manuálová stránka fyzicky je. Použijeme-li přepínač -w, zobrazí se cesta k souboru s manuálovou stránkou. Výhodné je kombinování přepínačů -w a -a.

$ man -w man
/usr/share/man/man1/man.1.gz
$ man -wa man
/usr/share/man/man1/man.1.gz
/usr/share/man/man1p/man.1p.gz
/usr/share/man/man7/man.7.gz
$

Prohlížení manuálových stránek v GUI

K manuálovým stránkám se přistupuje obvykle z příkazové řádky, ale existují také grafické prohlížeče. Jedním z nich je xman. V KDE lze použít také Konqueror, v němž se manuálové stránky hledají příkazem #stránka.

Konqueror *** xman

Struktura manuálových stránek

Manuálové stránky jsou často velmi rozsáhlé. Z tohoto důvodu existuje konvence, která určuje oddíly, z nichž by se, je-li to možné, měla každá manuálová stránka skládat. Není nutné použít v každé stránce všechny oddíly, ale je třeba, aby byly informace rozděleny podle toho, kam patří. V tabulce je seznam tradičních oddílů. Nemusíme však moc pátrat, abychom narazili na nějaké další. Někdy prostě standardní oddíly nestačí a někdy nejsou manuálové stránky vhodně napsané.

Tvorba manuálových stránek

Příkaz man ve skutečnosti pro formátování manuálových stránek využívá groff. groff je balíček obsahující několik programů.

Dobrým zvykem je psát manuálové stránky anglicky a až potom je lokalizovat.

Obvykle se manuálová stránka píše tak, že se jen zkopíruje jiná a ta je upravována. To je ve většině případů skutečně nejlepší řešení. Nicméně my si alespoň základy syntaxe objasníme. Jde jen o to, naučit se pár příkazů značkovacího jazyka troff, což je jazyk, ve kterém jsou manuálové stránky napsány.

Každý příkaz jazyka troff začíná tečkou, za níž následují písmena. Každý příkaz se píše na samostatný řádek. Příkazy mohou mít parametry. Do zdrojového kódu lze vkládat jednořádkové komentáře, které se označují sekvencí \".

viditelný text \" komentář

Manuálová stránka začíná příkazem .TH. Jeho syntaxe je následující:

.TH název sekce [datum] [zdroj] [manuál]

Název je jméno manuálové stránky. Při prohlížení příkazem man je název v horních rozích stránky. Sekce označuje sekci, kam stránka patří. Poslední tři parametry jsou nepovinné. Datum určuje čas poslední úpravy stránky. Zdrojem je obvykle název balíčku, kterého je program součástí. A konečně manuál je jméno manuálu, kam patří program.

Abychom si ukázali mimo syntaxe i nějakou praktickou ukázku, budeme předpokládat, že píšeme manuálovou stránku k česko-anglickému slovníku. Bude to stránka jen čistě pro ilustraci bez nějakého hlubšího významu. .TH řádek bude vypadat třeba takto:

.TH CS2EN 1 "2006-01-20"

Za .TH následuje oddíl NAME. K označení každého oddílu existuje značka .SH, jejímž parametrem je jméno oddílu. NAME je jediný povinný oddíl, neboť ho používají některé programy - například whatis. Syntaxe oddílu NAME vypadá takto:

.SH NAME
cs2en \- simple Czech-English dictionary

Nyní, když za sebou máme značku .TH a oddíl NAME, můžeme pokračovat ostatními oddíly. Ještě předtím si ale musíme představit několik dalších příkazů.

Začátek odstavce označuje .PP.

Pro nastavení odsazení se používá příkaz .TP. Parametrem může být velikost odsazení.

Následující tabulka obsahuje příkazy pro změnu písma. Vždy se aplikují na text, který je na řádku za nimi, a pokud zde není, tak na další řádek.

Existují ještě další značky, ale jejich studium ponechám na vás. Začít můžete třeba v man(7).

Během psaní manuálových stránek není od věci dodržovat těchto 5 konvencí:

• argumenty funkcí se píší vždy kurzívou, zbytek funkce tučně
• v oddílu SYNOPSIS jsou názvy souborů uváděny tučně, v ostatních oddílech kurzívou
• speciální makra se píší velkými písmeny a tučně
• chybové kódy se uvádějí tučně
• odkaz na jinou manuálovou stránku je vyjma názvu sekce tučný

A nyní můžeme postupovat dále. Oddíl SYNOPSIS bude obsahovat jediný řádek, ve kterém budou některá slova zvýrazněná.

.SH SYNOPSIS
.B cs2en
.RB [ options ]
list_of_words

Následuje oddíl DESCRIPTION:

.SH DESCRIPTION
.I cs2en
is simple program for translating Czech words into English.
The list_of_words is list of Czech words which you want to translate.
.PP
If the searching is unsuccesful and
.B \-\-exact
is not used, program will seek similar words. If there aren't similar words,
program will finish.

A další oddíly:

.SH OPTIONS
.TP
.B "\-h  \-\-help"
display help message and exit
.TP
.B "\-v \-\-verbose"
display version and exit
.TP
.B "\-r \-\-regexp"
interpret each word from list_of_words as regular expression
.TP
.B "\-e \-\-exact"
only exact matches will be printed

.SH EXAMPLE
.TP
.BR cs2en \ kamenolom
outputs "stone quarry"
.TP
\fBcs2en \-\-regexp \fR.*lom
outputs translation of all Czech words with suffix lom to English

.SH FILES
.TP
/usr/share/dict/cs2en.dic
This file contains Czech words with translations to English.

.SH AUTHORS
Jan Novak <jan@novak.cz>

.SH SEE ALSO
.BR sdcv (1)

Příkazy jsou natolik intuitivní, že snad není třeba komentář. Manuálové stránky se ukládají se stejnou příponou jako je název příslušné sekce. Zdrojový kód tedy uložíme do souboru cs2en.1. Pokud to je vyžadováno, zkomprimujeme pomocí gzip:

$ gzip cs2en.1

Manuálové stránky vyhledávané příkazem man jsou umístěny v adresářích uvedených v proměnné MANPATH.

$ echo $MANPATH
/usr/local/man:/usr/share/man:/usr/X11R6/man:/opt/gnome/share/man
$

Pokud je definována proměnná prostředí LANG, hledá se v těchto adresářích nejdříve podadresář se stejným jménem, jako je obsah této proměnné. Pokud máme tedy LANG nastavenou na cs, bude se nejprve hledat v $MANPATH/cs/man1 a až poté v $MANPATH/man1. To je princip lokalizace.

Naši anglickou verzi nakopírujeme do podadresáře man1. Nyní by měl fungovat příkaz man cs2en. Dále můžeme stránku počeštit a umístit do cs/man1.

demonstrační manuálová stránka

Tisk manuálových stránek

V případě, že bychom chtěli manuálovou stránku vytisknout, bude nejlepším řešením konverze do PostScriptu.

$ a2ps /tmp/ls.ps /usr/share/man/man1/ls.1.gz

Funguje i toto:

$ man -l -Tps zdroj.gz > cíl.ps
$ man -l -Tdvi zdroj.gz > cíl.dvi

Konverze do HTML

Na http://www.oac.uci.edu/indiv/ehood/man2html.html je k dispozici program man2html. Pomocí něj je možné exportovat manuálovou stránku do HTML. Konverze by měla fungovat i přes příkaz man.

$ man wget | man2html > /tmp/wget.html
$ man -l -Thtml wget.1.gz > wget.html

Další zdroje

• man(1), apropos(1), whatis(1) - manuálové stránky k jednotlivým příkazům
• man2html(1) - export manuálových stránek do HTML, ke stažení zde
• man(7), groff_man(7) - vytváření manuálových stránek
• česká lokalizace manuálových stránek
• článek Martina Podholy na abclinuxu.cz
• linuxové manuálové stránky