Linux v příkazech - manuálové stránky

Pojďme nahlédnout na téma manuálových stránek trochu více do hloubky. Podíváme se postupně na členění, příkazy, konverzi a jejich tvorbu.

26.1.2006 06:00 | Jiří Václavík | přečteno 27424×

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:

SkupinaPopis
1uživatelské - zde jsou ty nejběžnější příkazy
2systémová volání poskytované jádrem
3knihovní funkce - tedy dokumentace pro programátory (například dokumentace knihovny stdio)
4popisuje soubory v adresáři /dev
5formáty konfiguračních souborů - například syntaxe /etc/fstab
6hry
7různé
8příkazy správce systému - například příkaz reboot

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

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

OddílVýznamPopis
NAMEnázevjméno programu a několikaslovný popis
SYNOPSIScharakteristikarychlá informace, jak program použít
DESCRIPTIONpopisrozsáhlejší pojednání o funkci programu
RETURN VALUES nebo EXIT STATUSnávratová hodnotapopis návratových hodnot programu
OPTIONSvolbypopis přepínačů a argumentů, které program přijímá
EXAMPLES nebo USAGEpoužitípříklady použití programu
FILESsouborykonfigurační, datové apod. soubory, které program využívá
ENVIRONMENTprostředízde výčet proměnných prostředí, které program využívá
DIAGNOSTICSdiagnostikaseznam chyb, ke kterým může za běhu programu dojít
SECURITYbezpečnostnebezpečí, na která můžete během používání programu narazit
CONFORMING TOpřizpůsobenístandardy, které program dodržuje (například stdio vyhovuje normě ANSI C)
(ADDITIONAL) NOTESpoznámkycokoliv, co nelze zařadit jinam
BUGSchybyinformace co dělat, když objevíme v programu chybu
AUTHORautorautoři programu a kontakty
SEE ALSOpříbuzná témataodkazy na související manuálové stránky, případně WWW adresy apod.

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.

PříkazPopis
.Rnormální písmo
.Btučné písmo
.Ikurzíva
.BItext bude zobrazen po slovech střídavě tučně a kurzívou
.IBtext bude zobrazen po slovech střídavě kurzívou a tučně
.BRtext bude zobrazen po slovech střídavě tučně a normálně
.RBtext bude zobrazen po slovech střídavě normálně a tučně
.IRtext bude zobrazen po slovech střídavě kurzívou a normálně
.RItext bude zobrazen po slovech střídavě normálně a kurzívou

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í:

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.

cs2en

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

Online verze článku: http://www.linuxsoft.cz/article.php?id_article=1083