Manuálová stránka

Z Multimediaexpo.cz

Aktuální verze z 8. 11. 2024, 14:24

Manuálová stránka (2024)

Manuálová stránka (anglicky man page) tvoří základ dokumentace v unixových operačních systémů. Každá manuálová stránka je samostatný dokument a neobsahuje hypertextové odkazy. Zobrazují se pomocí příkazu man.

Manuálové stránky jsou základem otevřeného systému, který detailně prezentuje veškeré technické informace o fungování systému.

Projekt GNU používá formát GNU Texinfo, který obsahuje hypertextové odkazy, avšak není kompatibilní s novějšími a rozšířenějšími formáty jako jsou HTML, SGML a podobně.

Použití

Manuálové stránky se mohou zobrazovat v nápovědě grafického uživatelského rozhraní. V textovém rozhraní (v shellu) se pro zobrazení manuálových stránek používá příkaz man:

 man <nazev_stranky>

Například "man ftp". Stránky jsou typicky označeny zápisem "jmeno(cislo_sekce)", například ftp(1).

Stránka se stejným názvem se může vyskytovat i v několika sekcích manuálu, například pokud mají stejný název systémová volání, uživatelské příkazy nebo makra troff. Příkladem může být man(1) a man(7), nebo exit(1) a exit(3). Syntaxe pro přístup k jiným než implicitním manuálovým sekcím se liší v různých man implementacích. V Linuxu a *BSD je například syntaxe pro čtení printf(3):

 man 3 printf

Manuál pro programátory UNIXu byl poprvé vydán 3. listopadu 1971. Online manuálové stránky představilo až Unix Version 7 v roce 1979. V té době byla dostupnost online dokumentace díky systému manuálových stránek obrovským pokrokem. Dnes má téměř každá aplikace svoje manuálové stránky. Pokud nemá, berou to uživatelé Unixu jako známku nízké kvality. Některé projekty, jako třeba Debian, dokonce dodělávají manuálové stránky pro programy, kterým chybí.

Formát jedné stránky pro každou aplikaci, chybějící třídění sekcí a docela malé možnosti formátování však motivovaly vývoj alternativních dokumentačních systémů. Jen málokteré alternativy si získaly takovou oblibu jako původní man. Výjimkou je texinfo systém projektu GNU, raný a jednoduchý hypertextový systém.

Většina UNIXových aplikací s vlastním uživatelským rozhraním (obzvláště ty, které využívají vývojové prostředí GNOME či KDE) dnes poskytuje uživatelskou dokumentaci v HTML spolu s prohlížečem dokumentace zabudovaným v aplikaci.

Manuálové stránky jsou obvykle v angličtině, existují však i v dalších jazycích. Pokud jsou nainstalovány různé jazykové verze manuálové stránky, je možné jiný, než implicitně nastavený jazyk (viz locale) vyvolat například takto (první příkaz vypíše anglickou manuálovou stránku příkazu cp, druhý pak slovenskou):

 LANG=C man cp
 LANG=sk man cp

Implicitním formátem manuálových stránek je systém troff buď s makry (orientováno na vzhled) nebo s mdoc (orientováno na sémantiku). Díky tomu je možné převést manuálovou stránku do jazyka PostScript, dokumentu PDF nebo na řadu dalších textových či tiskových formátů. Většina lidí však preferuje původní terminálové rozhraní.

Sekce manuálu

Manuál je obvykle rozdělen do 8 očíslovaných sekcí v tomto pořadí (v BSD Unixu a Linuxu):

UNIX System V používá podobné číselné schéma s výjimkou sekce 4-Formáty konfiguračních souborů, sekce 5-Různé a sekce 7-Speciální soubory.

Některé systémy mají navíc i tyto sekce:

Sekce jsou dále děleny písmeny na subsekce. Například subsekce 3C obsahuje Volání knihovny jazyka C, 3M matematickou knihovnu atd. Důsledkem toho je i sekce 8 (Příkazy systémové administrace) někdy přesunuta do subsekce 1M k hlavním příkazům. Některá písmena subsekcí mají obecný význam:

Manuálové stránky jsou uloženy jako zdrojové kódy pro nroff. Většina man verzí uchovává v paměti formátovanou verzi posledních několika zobrazených stránek.

Uspořádání

Všechny manuálové stránky bývají uspořádány tak, aby byly zobrazitelné jednoduchým ASCII textem – bez jakéhokoliv zvýraznění textu nebo úpravy fontu. Všechny stránky obvykle obsahují následující hlavičky sekcí a to v následujícím pořadí.

• NAME (Jméno) – Jméno příkazu nebo funkce spolu s jednořádkovým popisem toho, co dělá.
• SYNOPSIS (Shrnutí) – U příkazu je přesný popis toho, jak se spouští a jaké má možnosti. U funkcí je seznam parametrů a příslušný hlavičkový soubor.
• DESCRIPTION (Popis) – Doslovný popis fungování příkazu nebo funkce.
• EXAMPLES (Příklady) – Několik příkladů běžného použití.
• SEE ALSO (Příbuzná témata) – Seznam příbuzných příkazů a funkcí.

Objevují se i další sekce, ale ještě nejsou dostatečně standardizovány. Patří mezi ně: OPTIONS (Volby), EXIT STATUS, ENVIRONMENT (Prostředí), KNOWN BUGS (Známé chyby), FILES (Soubory), AUTHOR (Autor), REPORTING BUGS (Oznamování chyb) a COPYRIGHT (Autorská práva)

Příbuzná témata

• Unix
• Příkazy v Unixu
• Specifikace operačních systémů nazývaných „Unix“
• UNIX System III
• Texinfo
• RTFM

Externí odkazy

• Archive.org – Manuál pro programátory UNIXu z 3. listopadu 1971 (anglicky)
• Archive.org – Úvod do TCL/TK

Repositář manuálových stránek

• ABC Linuxu – Manuálové stránky
• Umístění CS manuálových stránek
• Archive.org – Jak překládat manuálové stránky do češtiny
• Archive.org – On-line manuálové stránky Unixu (anglicky)
• Archive.org – Manuálové stránky Unixu / Linuxu, obsahují tisíce stránek z mnoha distribucí Unixu i Linuxu (anglicky)
• HTML manuálové stránky FreeBSD (anglicky)
• Manuálové stránky OpenBSD (anglicky)
• Archive.org – Manuál Plan 9 – Svazek 1 (anglicky)