Chcete, aby se váš nový program pro Linux prezentoval profesionálně? Vytvořte k němu manuálovou stránku. Ukážeme vám, jak na to snadno a rychle.
Manuálové stránky
V jednom starém vtipu o Unixu se říká: „Jediný příkaz, který potřebujete znát, je man.“ Manuálové stránky jsou zdrojem rozsáhlých informací a měly by být prvním místem, kam se podíváte, pokud chcete zjistit více o nějakém příkazu.
Když pro svůj nástroj nebo příkaz vytvoříte manuálovou stránku, povýšíte ho z pouhého užitečného kódu na plnohodnotný linuxový balíček. U programů určených pro Linux se automaticky očekává, že budou mít manuálovou stránku. Pokud vytváříte nativní linuxovou aplikaci, je manuálová stránka nezbytná, pokud chcete, aby byl váš program brán vážně.
V minulosti se manuálové stránky psaly za použití sady formátovacích maker. Když spustíte příkaz man pro zobrazení stránky, groff zpracuje soubor a vygeneruje formátovaný výstup podle maker v souboru. Výstup je následně zobrazen pomocí programu less pro vaše pohodlí.
Pokud nevytváříte manuálové stránky často, psaní a ruční vkládání maker může být velmi obtížné. Vytvoření manuálové stránky, která se správně analyzuje a vypadá dobře, může být náročnější než samotný cíl – poskytnout stručný a přitom důkladný popis vašeho příkazu.
Měli byste se soustředit na obsah, nikoli bojovat se složitou sadou maker.
Pandoc přichází na pomoc
Program Pandoc dokáže číst soubory v Markdownu a generovat výstup v asi 40 různých značkovacích jazycích a formátech dokumentů, včetně manuálových stránek. Tímto způsobem zcela transformuje proces vytváření manuálových stránek, takže se nemusíte trápit se složitými znaky.
Pro instalaci Pandocu v Ubuntu použijte tento příkaz:
sudo apt-get install pandoc
Ve Fedoře použijte následující příkaz:
sudo dnf install pandoc
V Manjaru zadejte:
sudo pacman -Syu pandoc
Sekce manuálové stránky
Manuálové stránky se dělí na sekce, které se řídí standardními konvencemi pro pojmenování. Sekce, které budete na své manuálové stránce potřebovat, závisí na složitosti příkazu, který popisujete.
Většina manuálových stránek obsahuje minimálně tyto sekce:
Název: Název příkazu a stručný popis jeho funkce.
Synopse: Krátký popis, jak lze příkaz spustit, včetně typů parametrů příkazového řádku.
Popis: Podrobnější vysvětlení účelu a funkce příkazu.
Možnosti: Seznam parametrů příkazového řádku a jejich popis.
Příklady: Několik příkladů běžného použití příkazu.
Výstupní hodnoty: Možné návratové kódy a jejich význam.
Chyby: Seznam známých chyb a omezení. Často je zde i odkaz na nástroj pro sledování problémů projektu.
Autor: Jméno osoby (osob), která příkaz napsala.
Copyright: Informace o autorských právech a licenci programu.
Pokud se podíváte na složitější manuálové stránky, zjistíte, že obsahují i další sekce. Například zkuste man man. Nemusíte ale zahrnovat všechny – stačí pouze ty, které jsou pro váš příkaz relevantní. Manuálové stránky nemají být obsáhlé, ale výstižné.
Mezi další často používané sekce patří:
Viz také: Další příkazy, které by mohly být užitečné nebo relevantní.
Soubory: Seznam souborů obsažených v balíčku.
Upozornění: Další důležité body, které je třeba znát.
Historie: Přehled změn v příkazu.
Části manuálu
Linuxový manuál se skládá ze všech manuálových stránek, které jsou rozděleny do následujících číslovaných sekcí:
| 1 | Spustitelné programy: Nebo příkazy shellu. |
| 2 | Systémová volání: Funkce poskytované jádrem. |
| 3 | Volání knihovny: Funkce v rámci programových knihoven. |
| 4 | Speciální soubory. |
| 5 | Formáty souborů a konvence: Například „/etc/passwd“. |
| 6 | Hry. |
| 7 | Různé: Balíčky maker a konvence, jako je groff. |
| 8 | Příkazy správy systému: Obvykle vyhrazené pro uživatele root. |
| 9 | Rutiny jádra: Obvykle nejsou standardně instalovány. |
Každá manuálová stránka musí uvést, do které sekce patří, a musí být uložena na správném místě pro tuto sekci, jak si ukážeme později. Manuálové stránky pro příkazy a nástroje patří do první sekce.
Formát manuálové stránky
Formát maker groff není snadno vizuálně čitelný, zatímco Markdown je mnohem přehlednější.
Níže vidíte příklad manuálové stránky v groff:
A zde je stejná stránka v Markdownu:
Úvodní údaje
První tři řádky tvoří takzvanou úvodní část. Každý z nich musí začínat znakem procenta (%), bez mezer na začátku, a s jednou mezerou za ním, následovanou:
První řádek: Obsahuje název příkazu, následovaný číslem sekce manuálu v závorkách, bez mezer. Název se stane levou a pravou částí záhlaví manuálové stránky. Konvenčně se název příkazu píše velkými písmeny, i když se objevují i jiné varianty. Vše, co následuje za názvem příkazu a číslem sekce, se stane levou částí zápatí. Zde se obvykle uvádí číslo verze softwaru.
Druhý řádek: Jméno (jména) autora (autorů). Ty se zobrazují v automaticky generované sekci „Autoři“ v manuálové stránce. Nemusíte přidávat sekci „Autoři“ – stačí zde uvést alespoň jedno jméno.
Třetí řádek: Datum, které se také stane střední částí zápatí.
Název
Sekce jsou označeny řádky, které začínají znakem čísla (#), což je označení pro nadpisy v Markdownu. Znak čísla (#) musí být první znak na řádku, následovaný mezerou.
Sekce „Název“ obsahuje stručný jednorádkový popis, který se skládá z názvu příkazu, mezery, pomlčky (-), mezery a velmi krátkého popisu funkce příkazu.
Synopse
Sekce „Synopse“ obsahuje různé formáty příkazového řádku, které může příkaz přijmout, například vyhledávací vzor nebo parametr. Dvě hvězdičky (**) na obou stranách názvu příkazu způsobí, že se název zobrazí tučně. Jedna hvězdička (*) na obou stranách způsobí podtržení.
Ve výchozím nastavení je každý nový řádek oddělen prázdným řádkem. Pokud chcete vynutit nový řádek bez prázdného řádku, použijte zpětné lomítko (\\) na konci řádku.
Popis
Sekce „Popis“ vysvětluje, co příkaz nebo program dělá. Měl by stručně, ale jasně popsat důležité detaily. Pamatujte, že nepíšete uživatelskou příručku.
Použitím dvou znaků čísla (##) na začátku řádku vytvoříte nadpis druhé úrovně. Můžete je použít k rozdělení popisu do menších částí.
Možnosti
V sekci „Možnosti“ popíšete všechny parametry příkazového řádku, které lze s příkazem použít. Podle konvence se zobrazují tučně, takže je ohraničte dvěma hvězdičkami (**). Na dalším řádku začněte popis parametru dvojtečkou (:), následovanou mezerou.
Pokud je popis dostatečně krátký, man jej zobrazí na stejném řádku jako parametr. Pokud je příliš dlouhý, zobrazí se jako odsazený odstavec pod parametrem.
Příklady
Sekce „Příklady“ obsahuje několik ukázkových použití příkazu. Všimněte si, že popisné řádky začínáme dvojtečkou (:), stejně jako v sekci „Možnosti“.
Výstupní hodnoty
Tato sekce uvádí návratové hodnoty, které příkaz odesílá zpět volajícímu procesu, ať už je to shell nebo skript. I zde začínáme popisné řádky dvojtečkou (:).
Chyby
Sekce „Chyby“ obsahuje seznam známých chyb, problémů nebo zvláštností, o kterých by uživatelé měli vědět. U open-source projektů je obvyklé uvést odkaz na nástroj pro sledování chyb, kde uživatelé mohou zkontrolovat stav chyb nebo nahlásit nové.
Copyright
Sekce „Copyright“ obsahuje vaše prohlášení o autorských právech a obvykle i popis typu licence, pod kterou je software vydán.
Efektivní pracovní postup
Manuálovou stránku můžete editovat ve svém oblíbeném textovém editoru. Většina editorů s podporou zvýrazňování syntaxe rozpozná Markdown a barevně odliší nadpisy, tučné písmo a podtržení. To je sice skvělé, ale skutečné zobrazení manuálové stránky uvidíte až v man.
pandoc ms.1.md -s -t man | /usr/bin/man -l -
Otevřete okno terminálu v adresáři, kde je uložen váš Markdown soubor. Během editace soubor pravidelně ukládejte. Po každém uložení můžete v terminálu spustit tento příkaz:
Po spuštění příkazu jej můžete opakovat stisknutím šipky nahoru a Enter.
Tento příkaz volá pandoc pro váš Markdown soubor (zde nazvaný „ms.1.md“):
Volba -s (standalone) generuje kompletní manuálovou stránku, nikoli jen text ve formátu man.
Volba -t (typ výstupu) s parametrem „man“ říká pandocu, aby vygeneroval výstup ve formátu man. Neříkáme pandocu, aby odeslal výstup do souboru, takže se odešle na stdout.
Tento výstup se také odesílá do man pomocí volby -l (local file), která mu říká, aby neprohledával databázi manuálových stránek, ale aby otevřel specifikovaný soubor. Pokud je název souboru -, man převezme vstup ze stdin.
To znamená, že můžete uložit změny v editoru a stisknout Q pro zavření man v okně terminálu. Potom můžete stisknout šipku nahoru a Enter, a uvidíte aktuální verzi vaší manuálové stránky přímo v man.
Vytvoření vaší manuálové stránky
pandoc ms.1.md -s -t man -o ms.1
Po dokončení manuálové stránky ji musíte vygenerovat a nainstalovat do systému. Následující příkaz řekne pandocu, aby vygeneroval manuálovou stránku s názvem „ms.1“:
Název souboru odpovídá konvenci pojmenování manuálových stránek, kde název příkazu je následován číslem sekce manuálu, jako by to byla přípona souboru.
manpath
Tento příkaz vytvoří soubor „ms.1“, což je naše nová manuálová stránka. Kam ji umístit? Příkaz manpath vám ukáže, kde man hledá manuálové stránky:
Výstup nám říká následující:/usr/share/man: Umístění standardní knihovny manuálových stránek. Stránky do této knihovny nepřidáváme./usr/local/share/man: Tento symbolický odkaz směřuje na „/usr/local/man“.
/usr/local/man: Zde musíme umístit naši novou manuálovou stránku.
Všimněte si, že jednotlivé sekce manuálu jsou umístěny v oddělených adresářích: man1, man2, man3 atd. Pokud adresář pro danou sekci neexistuje, musíme jej vytvořit.
sudo mkdir /usr/local/man/man1
Pro vytvoření adresáře použijte:
sudo cp ms.1 /usr/local/man/man1
Nyní zkopírujeme soubor „ms.1“ do správného adresáře. man očekává, že manuálové stránky budou komprimované, proto použijeme gzip:
sudo gzip /usr/local/man/man1/ms.1
:
sudo mandb
Chcete-li přidat nový soubor do databáze man, zadejte:
man ms
A je to! Nyní můžeme zobrazit naši novou manuálovou stránku stejně jako jakoukoli jinou zadáním:
Naše nová manuálová stránka se najde a zobrazí.
Vypadá stejně jako jakákoli jiná manuálová stránka, s tučným, podtrženým a odsazeným textem na správných místech.
Popisné řádky, které se vejdou vedle parametru, který popisují, se zobrazí na stejném řádku. Delší řádky se zobrazí pod popisem parametru.
Automaticky jsme také vygenerovali sekci „Autoři“. Zápatí také obsahuje číslo verze softwaru, datum a název příkazu, jak je definováno v úvodní části.
A pokud chcete . . .
Po vytvoření manuálové stránky pomocí pandocu můžete také přímo upravit soubor v groff formátu, a teprve poté jej zkopírovat do adresáře manuálových stránek a zkomprimovat.