přejít na obsah přejít na navigaci

Linux E X P R E S, Nebojíme se dokumentace

Nebojíme se dokumentace

manman.png

O linuxové komunitě se traduje, že je k nováčkům nepřátelská, že je arogantní a nafoukaná. V mnoha případech je to způsobeno tím, že nováček dostane na spoustu dotazů odpověď „Přečti si manuál“ nebo „Máš to v dokumentaci“ a hned si pomyslí něco o arogantních a namyšlených lidech. Ovšem ten největší rozdíl mezi člověkem nezkušeným a zkušeným je skutečnost, že ten druhý tu dokumentaci skutečně četl/čte. Kdo se naučí používat dokumentaci, stane se samostatnějším a svoje potíže bude řešit rychleji (navíc bude časem dokonce schopen radit dalším začátečníkům). To je cílem a účelem těchto odpovědí. Stát se nezávislým na pomoci ostatních.


reklama

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.

Obrázek:Prohlížení manuálových stránek v Konqueroru

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.

Obrázek: Automaticky generované hypertextové odkazy

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.

Obrázek: Stránka intro je ve více sekcích

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

  1. spustitelné nebo shellové programy;
  2. systémové volání (poskytované jádrem);
  3. knihovní funkce (poskytované knihovnami);
  4. speciální soubory (obvykle z adresáře /dev);
  5. formáty souborů a konvence (třeba passwd);
  6. hry;
  7. různé (včetně maker a konvencí, jako man(7) a groff(7));
  8. 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“.

Obrázek: GNU Texinfo stránka makrojazyka m4

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.

Obrázek: Lokálně instalovaná dokumentace jazyka Python 2.5

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

Obrázek:Centrum nápovědy KDE

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.

Nahoru

(Jako ve škole)
Průměr: 1,00 | Hodnotilo: 1
 

Top články z OpenOffice.cz

Příspěvky

Nebojíme se dokumentace
rudhas 1. 10. 2007, 16:43:01
Odpovědět  Odkaz 
je to určite pre bežneho použivatela??
Nebojíme se dokumentace
alphahun 11. 10. 2007, 13:27:24
Odpovědět  Odkaz 
Tento článok je obrovským prínosom pre začiatočníkov. Je to presne to, čo som pred pár mesiacmi hľadal a v takej ucelenej podobe nikde nenašiel. Napriek investícii do piatich kníh, prehľadávaní webu a študovaní manuálov včítane LDP....

Autorovi patri obrovská vďaka.

alphahun
Nebojíme se dokumentace
Jarda 22. 08. 2008, 11:18:15
Odpovědět  Odkaz 
Díky za článek. Už měsíc mne štve, že se nevyznám v syntaxi parametrů vypsaných pomocí 'man'. Zde jsou alespoň některé definice, doufejme, že platné v celé dokumentaci.

Přidat názor

Nejsou podporovány žádné značky, komentáře jsou jen čistě textové. Více o diskuzích a pravidlech najdete v nápovědě.
Diskuzi můžete sledovat pomocí RSS kanálu rss



 
 

Michal Vyskočil

Vystudoval FIT VUT v Brně. V současné době pracuje jako engineering manager v pražském SUSE. Nadšený uživatel Linuxu a open-source technologií. Autor mnoha článků na českých linuxových webech.


  • Distribuce: openSUSE
  • Hodnocení autora: *



Public Relations

QNAP uvedl novou modelovou řadu NAS TVS-x82T

Společnost QNAP uvedla na trh novou modelovou řadu NAS TVS-x82T, kterou tvoří tři různé modely (TVS-1282T, TVS-882T a TVS-682T). Nová řada je založena na vícejádrových procesorech Intel Core aktuální generace se 14nm výrobním procesem. Díky nim mohou nové NASy nabídnout dostatek výkonu i pro aplikace náročné na CPU.

Pokračování ...


CIO Agenda 2016