Manuálové stránky
Manuálové stránky jsou naprostým základem, starým jako Unix sám. Bez „kouzelného“ příkazu man by byli lidé, závislí na konzoli, zcela bezmocní, protože příkazů jsou stovky a počet jejich parametrů je řádově větší. Ovšem často jsou autory manuálových stránek programátoři, z čehož plyne, že pokud jí nerozumíte, nemusí být chyba na vašem přijímači. Slouží především jako „stručný“ (v uvozovkách proto, že taková stránka příkazu gcc čítá přes 11 tisíc řádků) popis funkce programu a jeho parametrů. Teorii v nich nehledejte. Základním příkazem, který je zobrazí, je man. Jako příklad manuálové stránky si uveďme (upravenou verzi) samotného příkazu man.
Manuálové stránky jsou rozděleny do oddílů. Samotná dokumentace příkazu man uvádí NAME, SYNOPSIS, DESCRIPTION, OPTIONS, FILES, SEE ALSO, BUGS a AUTHOR. Pochopitelně ne každá stránka musí obsahovat všechny a některé zavádějí i vlastní oddíly (například samotný man man má oddíl HISTORY).
Úplně první věcí, kterou byste si měli přečíst, je první řádek neboli hlavička stránky. Ta uvádí název příkazu psaný velkými písmeny, jenž je následován číslem sekce. Manuálové stránky jsou standardně rozděleny do osmi sekcí (jejichž význam je uveden v manuálové stránce příkazu man). Jejich význam zatím přeskočíme a přejdeme na první oddíl, kterým je vždy NAME (jméno). Tento segment je povinný a obsahuje stručný popis programu. Jak uvidíme dále, slouží k vyhledávání.
SYNOPSIS (souhrn, použití) bývá nejdůležitější částí, protože stručně uvádí všechny možné kombinace argumentů. Tato část je v závislosti na složitosti/schopnostech programu buďto velmi jednoduchá (ping(1)), nebo hodně složitá (ip(8)). Nejobvyklejší je tato forma zápisu: foo -i [-t|-u|-z] [-a [-b]] .
V něm má hypotetický příkaz foo povinný argument -i, dále trojici -t, -u, -v, které jsou volitelné, ale navzájem se vylučují (mnoho programů v tomto případě bere jako platnou volbu poslední argument, takže foo -i -t -u -z je stejné jako foo -i -z). Dalším volitelným argument je -a. Ovšem pokud jej zadáme, můžeme jej ještě upřesnit parametrem -b. Příkaz je foo -i -b neplatný. Hranaté závorky tedy popisují volitelné argumenty a znak roury | označuje vzájemně se vylučující argumenty.
Oddíl DESCRIPTION (popis) obsahuje podrobnější popis daného programu. Manuálová stránka příkazu man tedy říká: „Příkaz man je stránkovač systémové dokumentace. Každý název stránky, který příkaz man dostane jako argument, je obvykle název programu, utility nebo funkce. Manuálová stránka asociovaná s každým z argumentů je nalezena a zobrazena.“
Jak jsem uvedl výše, manuálové stránky jsou poměrně hutné technické texty, které se navíc poměrně obtížně překládají do češtiny.
Oddíl OPTIONS (volby) obsahuje informace o jednotlivých argumentech a přepínačích. Nejprve je uvedena volba (-k, --appropos) a teprve potom, na dalším řádku, popis. V našem případě se jedná o volbu, která pomáhá při vyhledávání a pro další detaily je nutné navštívit apropos(1).
Část FILES (soubory) potom obsahuje seznam relevantních souborů a adresářů, které k danému patří. Zde naleznete umístění konfiguračních souborů a podobně. Část SEE ALSO (viz také) potom odkazuje na manuálové stránky, které s touto tematicky souvisejí.
Grafické prohlížeče manuálových stránek
Pro některé uživatele není konzole příjemné prostředí, přesto i oni občas potřebují zabrousit do dokumentace. Zadáním man:/man(1) nebo #man(1) do adresního řádku Konqueroru se pomocí speciálního kio-slave převede manuálová stránka z formátu troff na HTML, které je následně zobrazeno v prohlížeči. Velkou výhodou jsou například automaticky generované hypertextové odkazy na další manuálové stránky. Velmi podobně pracuje i Nautilus v prostředí GNOME, kde stačí zadat man:man.
Vyhledávání
Příkaz man je velice užitečný, pokud známe příkaz, který chceme použít. Když máme potíže s připojením externí jednotky, bude man mount či man fstab to, co bez nějakého rozmýšlení zadáme. Ale co dělat, pokud chceme udělat něco, a nevíme čím? Odpověď zní - vyhledávání. Vzhledem k tomu, že zatím známe pouze man man, bude nejlepší se uchýlit tam.
Ovšem čtení celé stránky není nutné, daleko rychlejší je použít vyhledávání a postupně hledat slovo „search“ (jak vyhledávat, viz poznámku na okraji). Až se dostaneme k argumentu -k, který je uveden i v příkladu manuálové stránky. Jak říká dokumentace, prohledává tento příkaz stručný popis manuálové stránky, který je tvořen oddílem NAME. Pro další podrobnosti máme navštívit stránku apropos(1). Díky znalosti příkazu apropos(1) (respektive man -k) můžeme vyhledávat v manuálových stránkách. Dejme tomu, že hledáme aplikaci pro vypalování.
$ apropos burn k3b (1) - KDE CD burning program
Ovšem, ne vždy může být situace jednoznačná
$ apropos rip wpa_action (8) - wpa_cli action script
Protože program apropos(1) standardně bere jako úspěch i podřetězce. Pokud hledáme výhradně toto slovo, můžeme použít přepínač -e. Umí také regulární výrazy, ale o nich se více dočtete v dokumentaci.
Sekce
Manuálové stránky jsou členěny do osmi sekcí. Tedy těch osm je standardních a některé unixové systémy jich mohou mít i více. V Linuxu je tou sekcí „9 Kernel routines“ (funkce jádra). Klasické rozdělení je potom
- spustitelné nebo shellové programy;
- systémové volání (poskytované jádrem);
- knihovní funkce (poskytované knihovnami);
- speciální soubory (obvykle z adresáře /dev);
- formáty souborů a konvence (třeba passwd);
- hry;
- různé (včetně maker a konvencí, jako man(7) a groff(7));
- systémové příkazy (obvykle dostupné pouze uživateli root).
Příkazy se potom uvádějí jako program(sekce), což je konvence, která usnadňuje následné hledání v dokumentaci. Stejná stránka může být v několika sekcích, takže je občas nezbytné číslo sekce specifikovat. Typickým příkladem je manuálová stránka intro (o níž jsem se, mimochodem, dozvěděl právě z dokumentace), jež se nachází ve všech osmi sekcích. Pouhé man intro zobrazí stránku ze sekce 1. Pokud chcete přesné číslo, napište man cislo_sekce stranka. Pokud náhodou nevíte, ve které sekci daná stránka leží, podívejte se na význam argumentu -a příkazu man(1).
Další formáty dokumentace
GNU Texinfo
Jedná se o formát hierarchicky členěné dokumentace, kterou používají především programy vytvořené FSF. Poskytuje přehršel možností a ovládání prohlížeče manuálových stránek se blíží webovému prohlížeči. Ovšem Konqueror (stejně jako Nautilus) umí prohlížet i info stránky, takže není nezbytné se učit ovládat konzolový prohlížeč. Mnohdy také nalezneme v manuálové stránce pouze lakonické sdělení „Podívejte se do info stránky“.
Webová dokumentace
Protože je Linux velmi těsně spjat s rozvojem webu (na němž má kombinace Linux+Apache nemalý podíl), nevznikl tu žádný specifický formát dokumentace, jako tomu bylo u starších Unixů. Obrovská spousta dokumentace je dostupná ve formátu HTML (případně XML), která může být dostupná online na webu nebo offline na disku. Pokud je na disku, je jejím domovem adresář /usr/share/doc (respektive /usr/local/share/doc), takže, pokud máte nainstalován i dokumentační balík, máte k dispozici i příslušnou dokumentaci. Ovšem toto velmi silně dodržuje především Debian a na něm založené distribuce, jinde se můžeme setkat i s /usr/doc. Bohužel FHS se o umístění dokumentace nezmiňuje.
FAQ – Frequently Asked Questions
Neboli ČKD (Často kladené dotazy) jsou zdrojem odpovědí, které kladou většinou začátečníci. Bývá neslušné pokládat dotaz, jehož odpověď už ve FAQ visí, protože tyto dokumenty vznikají především proto, aby těmto dotazům v budoucnu zabránily. Bývají koncipovány jako dvojice otázka a stručná odpověď. Ovšem občas se rozsahem blíží k HOWTO.
HOWTO
Neboli Jak na to. Formálním rozdílem mezi HOWTO a FAQ je rozsah. Typická odpověď z FAQ má jednu dvě věty, kdežto HOWTO dokumenty jsou rozsáhlejší a uvádějí i nezbytné teoretické podklady. Aby nebyla situace tak jednoduchá, existují mikro HOWTO, což jsou dokumenty o několika málo stranách, které popisují daný problém stručněji.
Systém nápovědy desktopového prostředí
Přestože má část programů z prostředí KDE/GNOME manuálové stránky, většina dokumentace je dostupná přes systém nápovědy. Obě dvě mají vlastní aplikace pro prohlížení dokumentace, které jsou dostupné z hlavní nabídky nebo z menu jednotlivých aplikací. Ovšem obě prostředí umí číst i manuálové a info stránky.
Závěr
Čtení dokumentace je velmi užitečnou dovedností při pronikání do tajů Linuxu. Pokud vám někdo odpoví odkazem na ni (ono proslavené RTFM), je tomu tak proto, že když se ji naučíte efektivně používat, bude vaše cesta Linuxem jednodušší a samostatnější a řešení vašich problémů bude rychlejší. Přesně v duchu čínského přísloví „Dej člověku rybu a nasytíš ho na jeden den, nauč ho rybařit a nasytíš jej na celý život“.
Dodatky
Roff, nroff(1), troff(1) a groff(1)
Jazyk, v němž jsou manuálové stránky napsány, se nazývá troff(1). Jedná se o značkovací makrojazyk, podobně jako TeX. Tři pojmy v nadpise nejsou chybou, ale přibližně ukazují historický vývoj z původního jazyka roff, který vyvinula AT&T pro účely sázení textu. Nroff(1) je jedna z větví, která ovšem nepřežila smrt svého tvůrce, a původní troff(1) je dílem Briana Kerninghena. No a groff(1) je GNU reimplementací těchto dvou systémů, který přidává nové vlastnosti, aby pokryl požadavky vznikajících OSS unixových systémů.
Pochopitelně nepřežil rozmach pokročilejších, ale náročnějších systémů, jako třeba TeX, nebo FrameMaker. V dnešní době se používá pouze pro psaní unixových manuálových stránek. To, že se jedná o sázecí systém, je velice hezky vidět na tom, že jsou manuálové stránky vždy zarovnány do bloku.
Ukázka dokumentu v troff .TH "SU" "1" "06/06/2006" "User Commands" "User Commands" .nh .ad l .SH "NAME" su \- change user ID or become super\-user
Jak vidíte, tak příkazy jazyka troff začínají na novém řádku s tečkou. Podobný formát používal legendární editor T602.
Vyhledávání v dokumentaci
Manuálové stránky fungují v duchu unixové tradice, kterou je „program dělá jednu práci a dělá ji dobře“. Samotný příkaz man tudíž neobsahuje žádný stránkovač, protože se plně spoléhá na schopnosti externího programu. Na většině linuxových systémů to bývá less(1), který umožňuje vyhledávání stisknutím klávesy [/] (další unixová tradice). Ovšem grafické prohlížeče mají konvenční hledání pomocí dialogů a klávesových zkratek. Pro více informací si přečtěte less(1), pro změnu stránkovače si nastudujte použití přepínače -P v man(1). Starším a jednodušším stránkovačem je more(1), daleko pokročilejším, ale běžně neinstalovaným, je most(1).
Docbook
Jedná se o XML (i SGML) formát pro psaní dokumentace. Ve světě open source se jedná o defacto standard. Mimo jiné umožňuje konverzi do formátů troff, HTML, RTF nebo PDF. Je v něm psána spousta dokumentace, včetně té k prostředí KDE a GNOME nebo API GTK+, případně dokumentace k jádru. Technicky jde o sadu definic ve formátu DTD a XML Schema, které popisují sémantiku výsledného dokumentu.
