10. Manuálové stránky

Vývoj vanilkové příchuti Linuxu: Knihy kouzel byl 1. března 2025 ukončen. Tento text je zachován jako historický, ale chyby již nejsou opravovány. Odnože projektu pod kompatibilní licencí jsou vítány.

dokumentace syntaxe tematický okruh

1. Úvod

Tato kapitola pokrývá zobrazování, správu a vytváření manuálových stránek v linuxu.

Manuálové stránky jsou hlavním zdrojem základních informací o příkazech v terminálu (např. „ps“), vlastnostech a funkcích operačního systému (např. „fstab“) a funkcích v programovacích jazycích (např. „strcpy“).

2. Definice

Název je základní označení manuálové stránky bez dalšího upřesnění (např. „printf“ či „git-config“). V názvech se nerozlišuje velikost písmen, ale obvykle se píšou malými písmeny a slova se oddělují pomlčkami.
Manuálové stránky se nacházejí v číslovaných manuálových sekcích (něco jako adresáře, neplést si se sekcemi manuálových stránek).
Anotace je velmi stručné, jednořádkové shrnutí činnosti příkazu, programu či funkce, které manuálová stránka poskytuje v sekci „JMÉNO“ („NAME“).
Každá manuálová stránka se člení na sekce manuálové stránky a podsekce, více úrovní členění není podporováno.

Protože je běžné, že pod jedním názvem existují manuálové stránky v několika různých manuálových sekcích, pro úplné určení je nutné uvést název manuálové stránky i označení manuálové sekce; pro to existuje několik nekompatibilních syntaxí:

passwd(5)
passwd.5
passwd (5)

3. Zaklínadla: hlavní

^3/1 Zobrazit manuálové stránky

@zobrazit m. stránku (obecně/příklady)#1 ⁽¹⁾

man název[.sekce]

man man

man apt-get.8

@zobrazit postupně více m. stránek (obecně/příklad)#2 ⁽²⁾

man -a --no-subpages název[.sekce] [název[.sekce]]

man -a --no-subpages git.1 diff sudo.8 apt-get.8

@vypsat anotaci#3

whatis [-s sekce] název

@zobrazit m. stránku z konkrétního souboru#4 ⁽³⁾

man -l [--] cesta/k/souboru

@zobrazit m. stránku a přejít na určitou sekci#5

@zobrazit všechny m. stránky, jejichž název odpovídá regulárnímu výrazu#6

man --names-only --regex [-s výčet,m.,sekcí]] [--] 'regulární výraz'

^3/2 Seznamy manuálových stránek

@seznam všech dostupných m. str.#1

man [-s výčet,m.,sekcí] -k . [| sort] [| less]

@všech m. str. v man. sekci 1#2

man -s 1 -k . | sort [| less]

@seznam m. str. dostupných v češtině (jen úplné názvy)#3

printf %s\\n /usr/share/man/cs/man*/*.*.gz | sed -E 's/^(.*)\/(.*)\.([^.]+)\.gz$/\2(\3)/' [| sort]

@seznam m. str. podle klíčového slova#4

apropos klíčovéslovo

@seznam manuálových stránek, jejichž identifikátor odpovídá regulárnímu výrazu (obecně/příklad)#5

man [-s výčet,m.,sekcí] -k 'regulární výraz' [| sort]

man -s 8 -k '^apt($|-)' | sort

^3/3 Pokročilá práce s manuálovými stránkami

@vypsat cestu k m. stránce/více m. stránkám#1 ⁽⁴⁾

man -w [-s sekce] název

man -wa [-s výčet,m.,sekcí] název

@vypsat sekce a podsekce m. stránky#2

@zkontrolovat syntaxi zdrojového kódu m. stránky#3

4. Zaklínadla: syntaxe manuálové stránky

^4/1 Hlavní prvky

@obecná struktura manuálové stránky#1 ⁽⁵⁾

[komentáře]

.TH "Název dokumentu" ČísloSekce ["Dole uprostřed" ["Dole vlevo" ["Nahoře uprostřed"]]]

.SH "NADPIS PRVNÍ SEKCE"

NÁZEV - anotace

...

@komentář (varianta A/varianta B)#2 ⁽⁶⁾

Kdekoliv na řádku:

\"Text komentáře do konce řádky

\#Text komentáře do konce řádku

^4/2 Formátování odstavců

@nadpis sekce/podsekce#1 ⁽⁷⁾

.SH "TEXT NADPISU"

.SS "Text nadpisu"

@předěl odstavce#2

.PP

@seznam definic#3 ⁽⁸⁾

.TP

[\fB]Hlavní štítek

[.TQ

[\fB]Vedlejší štítek]

Text definice

[.PP]

@zarovnat následující odstavce vlevo#4

.PP

.ad l

@zarovnat následující odstavce do bloku#5

.PP

.ad b

@zvýšit úroveň odsazení#6 ⁽⁹⁾

.RS

[.PP]

@snížit úroveň odsazení#7 ⁽¹⁰⁾

.RE

[.PP]

@ukončit odsazení#8 ⁽¹¹⁾

.RE 1

[.PP]

@zarovnat následující odstavce na střed#9

.PP

.ad c

@zarovnat následující odstavce vpravo#10 ⁽¹²⁾

.PP

.ad r

^4/3 Formátování písma

@přepnout na tučné/podtržené/normální písmo (do konce odstavce)#1 ⁽¹³⁾

...\fB...

...\fI...

...\fR...

@povinná volba#2

\fBvolba[ \fIargument]\fR

@volitelná volba#3 ⁽¹⁴⁾

.OP volba [argument]

@ukázka kódu (<pre>)#4 ⁽¹⁵⁾

.EX

řádky kódu

.EE

@hypertextový odkaz#5 ⁽¹⁶⁾

.UR URI

Text odkazu

.UE [Text za odkazem.]

^4/4 Přepínače

@odsazení a konce řádek: zachovat/zploštit na mezeru (jako v HTML)#1 ⁽¹⁷⁾

.nf

.fi

@vypnout/zapnout lámání slov (hyphenation)#2

.nh

.hy

^4/5 Speciální znaky

@tečka na začátku řádky#1 ⁽¹⁸⁾

\&....

@nezlomitelná mezera#2 ⁽¹⁹⁾

@ASCII znaky: „-“, „\“, „'“, „"“, „`“, „^“, „~“#3 ⁽²⁰⁾

\- \\ \(aq \(dq \(ga \(ha \(ti

@konec řádky/prázdný řádek#4

.br

.sp

@volitelný zlom slova (v případě zlomu vložit pomlčku)#5

@zakázat zlom slova#6

Před první znak slova vložte:

@copyright#7

\(co

@plná kulatá odrážka#8

\(bu

5. Parametry příkazů

^5/1 man

[MANWIDTH=počet-znaků] man parametry název

☐ -a	zobrazit postupně stejnojmenné stránky ze všech prohledaných sekcí (jinak se zobrazí jen první nalezená)
☐ -L en_US	manuálové stránky zobrazovat výhradně v angličtině
☐ --nh ☐ --nj	Zakázat lámání slov/zarovnání do bloku.

Nastavením proměnné prostředí „MANWIDTH“ lze určit, na jakou šířku se výstup příkazu „man“ zformátuje. Ve výchozím stavu se zformátuje na šířku terminálu (což je obvykle to, co chcete).

^5/2 Instalace manuálových stránek

Manuálové stránky v angličtině se umísťují do adresářů /usr/share/man/mansekce, musejí být komprimované ve formátu „.gz“ a mít název „název.sekce.gz“ (např. „apt-get.8.gz“). Manuálové stránky v češtině se umísťují do adresářů /usr/share/man/cs/mansekce. Pokud odpovídající adresář neexistuje (což se stává především u českých manuálových stránek), budete ho muset vytvořit.

6. Instalace na Ubuntu

Manuálové stránky a nástroje pro práci s nimi jsou základní součástí Ubuntu přítomnou i v minimální instalaci.

7. Ukázka

.TH "MOJE" 1 "14.\~ledna\~2020" "Moje vlastní stránky"

.SH "JMÉNO"

moje - moje první manuálová stránka

.SH "POUŽITÍ"

.SY moje

[\fB\-x\fR]

.OP -y test

.YS

.SH "POPIS"

Toto je moje první vlastní manuálová stránka. K\~ jejímu napsání mi pomohl

Linux: Kniha kouzel.

.PP

Delší ukázkou je:

\(bu manuálová stránka dodávaná ke spouštěči \fBlkk\fR.

8. Tipy a zkušenosti

Častou začátečnickou chybou je očekávání, že když za příkaz „man“ zadáte více neúplných názvů, zobrazí manuálovou stránku pro každý z nich. Jenže to funguje jen někdy, takže se dříve nebo později „spálíte“. Zkuste, co udělá příkaz „man apt get“ (nebo pokud máte nainstalovaný git, můžete zkusit „man git diff“).
Prázdné řádky ve zdrojovém kódu manuálové stránky jsou tiše ignorovány. Pomocí příkazů lze vložit nanajvýš jeden zcela prázdný řádek, více prázdných řádek se při zobrazení sloučí do jedné.
Pro většinu uživatelů jsou nejužitečnější manuálové sekce 1 (patří běžné uživatelské příkazy), 8 (příkazy pro správu systému) a 5 (dokumentace konfiguračních souborů, souborových systémů a dalších prvků operačního systému).
Na místě souboru s m. stránkou může být symbolický odkaz na jiný takový soubor; toho lze využít k vytváření „aliasů“.

^8/1 Obvyklé názvy sekcí m. stránky

Toto jsou sekce obvyklé na jedné manuálové stránce; neplést si s manuálovými sekcemi.

1. JMÉNO (NAME)
2. POUŽITÍ (SYNOPSIS)
3. POPIS (DESCRIPTION) — Obvykle se dělí na podsekce a obsahuje podrobný popis.
4. VOLBY (OPTIONS)
5. PŘÍKLADY (EXAMPLES) (volitelná)
6. POZNÁMKY (NOTES) (volitelná)
7. LICENCE (LICENSE) (má smysl hlavně u svobodného software)
8. VIZ TAKÉ (SEE ALSO) (volitelná)

9. Další zdroje informací

Wikipedie: Manuálová stránka
YouTube: Dokumentace příkazů
YouTube: Programování v shellu 4
ABC Linuxu: Manuálové stránky
YouTube: Mastering Linux Man Pages (anglicky)
YouTube: Write your own man page in Linux (anglicky)
man groff_man.7, man groff.7 (anglicky, nutno doinstalovat balíček „groff“)
TL;DR: man (anglicky)
Oficiální stránka jaderného projektu manuálových stránek (anglicky)
Oficiální stránky man-db (anglicky)
Balíček man-db (anglicky)

10. Zákulisí kapitoly

V této verzi kapitoly chybí:

Tato kapitola záměrně nepokrývá:

1 Uvedete-li v tomto zaklínadle na místo názvu více parametrů, příkaz man se je nejprve pokusí složit pomlčkami. Teprve pokud takovou m. stránku nenajde, zkusí zpracovat každý parametr zvlášť.

2 Pokud znáte sekce, z nichž chcete stránky zobrazit, doporučuji při zobrazování více stránek zadávat jejich úplné názvy. Zabráníte tím zobrazení stejnojmenných m. stránek z nechtěných sekcí.

3 Zadaný soubor může, ale nemusí být komprimovaný příkazem „gzip“. Na název a umístění zadaného souboru nejsou kladena žádná zvláštní omezení. (Ale pokud název začíná pomlčkou, musíte použít oddělovač „--“.)

4 Je-li m. stránka dostupná ve více lokalizacích, příkaz s parametrem „-a“ je vypíše všechny.

5 Obvyklé je „Dole uprostřed“ uvést datum poslední úpravy manuálové stránky, „Dole vlevo“ uvést název a verzi balíčku či projektu a „Nahoře uprostřed“ neuvádět.

6 Varianta A se vyhodnotí jako konec řádky; varianta B se zcela vypustí (tzn. řádek s komentářem se po vypuštění komentáře sloučí s následujícím řádkem).

7 Oba typy nadpisů ruší odsazení. Nadpisy sekcí je zvykem psát VELKÝMI PÍSMENY, ačkoliv to „man“ nevynucuje.

8 Formátovací přepínač v každém štítku platí jen do konce štítku. To platí i u posledního vedlejšího štítku.

9 Samotný příkaz „.RS“ ukončí řádek, ale nikoliv odstavec, proto i typ písma zůstává zachovaný.

10 Samotný příkaz „.RE“ ukončí řádku, ale nikoliv odstavec, proto i typ písma zůstává zachovaný.

11 Samotný příkaz „.RE 1“ ukončí řádek, ale nikoliv odstavec, proto i typ písma zůstává zachovaný.

12 Zarovnání odstavců vpravo v podání manuálových stránek nevypadá moc dobře; než se rozhodnete ho použít, raději ho nejprve vyzkoušejte.

13 Místo podtrženého písma mohou některé terminály zobrazovat text kurzívou. Mezery uprostřed podtrženého textu nebudou podtrženy.

14 Tento příkaz vypíše: obyčejným písmem „[“, tučně volbu, podtrženým písmem argument (je-li uveden) a obyčejným písmem „]“, to vše oddělené mezerami. Používá se především v „synopsi“ příkazu. Pokud volba nebo argument obsahují mezeru, je nutno příslušnou část uzavřít do dvojitých uvozovek.

15 Uvnitř bloku „.EX“ až „.EE“ neprobíhá automatické zalamování řádků a jejich odsazení mezerami či tabulátory bude na výstupu zachováno; použije se neproporcionální písmo (v terminálu je totéž jako to normální). Ostatní příkazy jsou však interpretovány.

16 V terminálu se hypertextový odkaz realizuje tak, že se vypíše text odkazu a za ním URI v kulatých závorkách. Při exportu do HTML se ovšem vytvoří skutečný hypertextový odkaz.

17 Poznámka: přepínač „.nf“ nevypne zalamování příliš dlouhých řádek.

18 Také pomůže před tečku umístit přepínač typu písma (např. „\fR“).

19 Pokud místo této značky použijete přímo nezlomitelnou mezeru, ta se neroztáhne při zarovnání do bloku a bude podtržena v případě přepnutí na podtržené písmo.

20 Pokud tyto znaky použijete přímo, terminál místo nich může zobrazit jiné, podobné znaky, což může způsobit problémy, pokud se je uživatel pokusí z manuálové stránky vykopírovat. Zpětné lomítko přímo použít nemůžete.

Markdown

Bash / Interaktivní režim

Proměnné prostředí a interpretu