Formát reStructuredText je velmi propracovaný formátovací jazyk, který je bohužel také opomíjený. Přitom toho umí v základu daleko více než oblíbený MarkDown. Jeden z možných způsobů použití je generování jiného pro člověka docela nečitelného značkovacího jazyka Groff. Groff (GNU troff) je na unixových systémech velmi rozšířen. Jsou v něm totiž psané manuálové stránky.
Ke generování manuálových stránek z rst souborů je určen příkaz rst2man. Pokud by chtěl někdo generovat stránky v python programu, například v setup.py, je možné použít přímo Writer z modulu docutils.writers.manpage.
ukázka volání příkazu rst2man
ukázka použití knihovny docutils v jazyce Python
Ať už budeme generovat manuálové stránky jedním, nebo druhým způsobem, důležité je pro nás obash vygenerované stránky, a to, jak se k němu dopracovat. Manuálová stránka může obsahovat následující části (kapitoly).
NAME
Jediná povinná kapitola manuálové stránky. Má obsahovat název manuálové stránky, resp. příkazu či funkce, k níž je manuálová stránka vytvořena a krátký popis.
SYNOPSIS
Obsahuje způsob volání. Způsobů může být více. Tato kapitola se používá i pro výčet aliasů, případně mutací.
DESCRIPTION
Textově bohatší popis, vysvětlující co daný příkaz, resp. funkce provádí.
OPTIONS
Seznam argumentů, včetně dokumentace, jak daný argument ovlivňuje volání, resp. jak ovlivňuje výsledek.
FILES
Seznam souborů, které jsou používány. Typicky jde o konfigurační a datové soubory, popis jejich priorit atd.
ENVIRONMENT
Seznam proměnných prostředí, které jsou používány.
DIAGNOSTICS
Tato kapitola slouží pro přehled chybových stavů, které mohou být funkcí, nebo příkazem vyvolány. Typicky jde o seznam chybových kódů a jejich vysvětlení.
BUGS
Do této kapitoly se obvykle píší instrukce pro hlášení chyb od uživatelů.
AUTHOR
Autor, resp. autoři manuálové stránky.
SEE ALSO
Poslední kapitola obsahuje související stránky. Jde o odkazy na další příkazy nebo funkce, které z nějakého důvodu mohou souviset s aktuální manuálovou stránkou. Například podobné příkazy, nebo funkce, které jsou volané.
Manuálová stránka také obsahuje sekci, ve které se vyskytuje. Těch je celkem osm a jsou číslované od jedné:
1 - obecné, nebo uživatelské příkazy
2 - systémová volání
3 - knihovní funkce jazyka C
4 - speciální soubory, soubory zařízení a ovladače
5 - formáty, např. konfiguračních souborů
6 - hry a spořiče obrazovky
7 - různé
8 - příkazy systémové administrace a démoni
Některé systémy mají navíc i další sekce, pro bližší informace proto odkazuji laskavého čtenáře na specifika jeho operačního systému, resp. uživatelského prostředí.
Ostatní informace jsou už jen drobnosti, ale utváří stránku jako celek. Patří mezi ně skupina. Tu používají například nástroje balíčku Core Utils. Dál je to datum poslední úpravy manuálové stránky, a také verze, ke které je manuálová stránka vygenerovaná.
ukázkový zdroj manuálové stránky foo.rst
Pozorný čtenář si zde zajisté všimne, že některé sekce chybí, například NAME a AUTHOR. Tyto sekce ale vytvoří docutils sami z názvu (hlavičky dokumentu) a příslušných atributů. Zdroj a vygenerovaná html stránka ale vypadají podobně jako manuálová stránka, proto tento způsob považuji za lepší cestu.
© 2025 Ondřej Tůma McBig. Ondřej Tůma | Based on: Morias | Twitter: mcbig_cz | RSS: články, twitter