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 22018×

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ů

13.9.2017 8:00 /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 – tentokrát netradičně v pondělí: 18. září od 18:00 v Radegastovně Perón (Stroupežnického 20, Praha 5).


Přidat komentář

3.9.2017 20:45 /Redakce Linuxsoft.cz
PR: Dne 21. září 2017 proběhne v Praze konference "Mobilní řešení pro business". Hlavní tématy konference budou: nejnovější trendy v oblasti mobilních řešení pro firmy, efektivní využití mobilních zařízení, bezpečnostní rizika a řešení pro jejich omezení, správa mobilních zařízení ve firmách a další.
Přidat komentář

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ář

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

> Poslední diskuze

18.9.2017 14:37 / Rojas
high security vault

15.9.2017 7:33 / Wilson
new zealand childcare jobs

31.8.2017 12:11 / Jaromir Obr
Re: ukůládání dat ze souboru

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

27.7.2017 12:24 / Jaromir Obr
Cteni/zapis

Více ...

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