LINUXSOFT.cz Přeskoč levou lištu
Uživatel: Heslo:  
   CZUKPL

> 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 | Články autora | přečteno 21744×

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

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

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

Verze pro tisk

pridej.cz

 

DISKUZE

Nejsou žádné diskuzní příspěvky u dané položky.



Příspívat do diskuze mohou pouze registrovaní uživatelé.
> Vyhledávání software
> Vyhledávání článků

15.5.2017 23:50 /František Kučera
Máš rád svobodný software a hardware nebo se o nich chceš něco dozvědět? Zajímá tě DIY, CNC, SDR nebo morseovka? Přijď na sraz spolku OpenAlt, který se bude konat ve čtvrtek 18. května od 18:00 v Radegastovně Perón (Stroupežnického 20, Praha 5).
Přidat komentář

12.5.2017 16:42 /Honza Javorek
PyCon CZ, česká konference o programovacím jazyce Python, se po dvou úspěšných ročnících v Brně bude letos konat v Praze, a to 8. až 10. června. Na konferenci letos zavítá např. i Armin Ronacher, známý především jako autor frameworku Flask, šablon Jinja2/Twig, a dalších projektů. Těšit se můžete na přednášky o datové analytice, tvorbě webu, testování, tvorbě API, učení a mentorování programování, přednášky o rozvoji komunity, o použití Pythonu ve vědě nebo k ovládání nejrůznějších zařízení (MicroPython). Na vlastní prsty si můžete na workshopech vyzkoušet postavit Pythonem ovládaného robota, naučit se učit šestileté děti programovat, efektivně testovat nebo si v Pythonu pohrát s kartografickým materiálem. Kupujte lístky, dokud jsou.
Přidat komentář

2.5.2017 9:20 /Eva Rázgová
Putovní konference československé Drupal komunity "DrupalCamp Československo" se tentokrát koná 27. 5.2017 na VUT FIT v Brně. Můžete načerpat a vyměnit si zkušenosti z oblasti Drupalu 7 a 8, UX, SEO, managementu týmového vývoje, využití Dockeru pro Drupal a dalších. Vítáni jsou nováčci i experti. Akci pořádají Slovenská Drupal Asociácia a česká Asociace pro Drupal. Registrace na webu .
Přidat komentář

1.5.2017 20:31 /Pavel `Goldenfish' Kysilka
PR: 25.5.2017 proběhne v Praze konference na téma Firemní informační systémy. Hlavními tématy jsou: Informační systémy s vlastní inteligencí, efektivní práce s dokumenty, mobilní přístup k datům nebo využívání cloudu.
Přidat komentář

15.4.2017 15:20 /František Kučera
Máš rád svobodný software a hardware nebo se o nich chceš něco dozvědět? Zajímá tě IoT a radiokomunikace? Přijď na sraz spolku OpenAlt, který se bude konat ve středu 19. dubna od 18:30 v Šenkovně (Sokolská 60, Praha 2).
Přidat komentář

5.3.2017 19:12 /Redakce Linuxsoft.cz
PR: 23. března proběhne v Praze konferenci na téma Cloud computing v praxi. Hlavními tématy jsou: Nejžhavější trendy v oblasti cloudu a cloudových řešení, Moderní cloudové služby, Infrastruktura současných cloudů, Efektivní využití cloudu, Nástrahy cloudových řešení a jak se jim vyhnout.
Přidat komentář

27.2.2017 22:12 /František Kučera
Pozvánka na 137. sraz OpenAlt – Praha: Tentokrát jsme si pro vás připravili neobvyklou akci. Ve středu 1.3. v 17:30 nás přivítá sdružení CZ.NIC ve svých prostorách v Milešovské ulici číslo 5 na Praze 3, kde si pro nás připravili krátkou prezentaci jejich činnosti. Následně navštívíme jejich datacentrum pod Žižkovskou věží. Provedou nás prostory, které jsou běžnému smrtelníkovi nedostupné!
Po ukončení prohlídky se všchni odebereme do hostince U vodoucha, Jagelonská 21, Praha 3 pochutnat si na některém z vybraných piv či dát si něco na zub. Rezervaci máme od 19:30, heslo je OpenAlt.
Ale pozor! Do prostor datového centra máme omezený přístup, dostane se tam pouze 10 lidí! Takže kdo přijde dříve, ten má přednost, a občanky s sebou! Kdo nebude chtít na prohlídku datového centra, může se pomalu přesunout do hostince U vodoucha a u nepřeberné nabídky piv počkat na ostatní.
Přidat komentář

18.1.2017 0:49 /František Kučera
Členové a příznivci spolku OpenAlt se pravidelně schází v Praze a Brně. Fotky z pražských srazů za uplynulý rok si můžete prohlédnout na stránkách spolku. Příští sraz se koná už 19. ledna – tentokrát je tématem ergonomie ovládání počítače – tzn. klávesnice, myši a další zařízení. Také budete mít příležitost si prohlédnout pražský hackerspace Brmlab.
Přidat komentář

   Více ...   Přidat zprávičku

> Poslední diskuze

1.8.2017 7:32 / Cassidy
structural consultants

30.7.2017 11:12 / Jaromir Obr
Národní znaky

27.7.2017 12:24 / Jaromir Obr
Cteni/zapis

26.7.2017 21:12 / Jaromir Obr
Podminka

15.6.2017 9:34 / Ondřej Havlas
php,

Více ...

ISSN 1801-3805 | Provozovatel: Pavel Kysilka, IČ: 72868490 (2003-2017) | mail at linuxsoft dot cz | Design: www.megadesign.cz | Textová verze