Jak vytvořit man Page na Linuxu

Chcete, aby váš nový linuxový program vypadal profesionálně? Dejte tomu manuálovou stránku. Ukážeme vám nejjednodušší a nejrychlejší způsob, jak to udělat.

Muž Pages

Ve starém unixovém vtipu je jádro pravdy, „the pouze příkaz, který potřebujete vědět je člověk.“ Manuálové stránky obsahují velké množství znalostí a měly by být prvním místem, kam se obrátíte, když se chcete dozvědět o příkazu.

Poskytnutí manuálové stránky pro obslužný program nebo příkaz, který jste napsali, jej povýší z užitečného kódu na plně vytvořený linuxový balíček. Lidé očekávají, že bude poskytnuta manuálová stránka pro program, který byl napsán pro Linux. Pokud nativně podporujete Linux, je manuálová stránka povinná, pokud chcete, aby byl váš program brán vážně.

Historicky byly manuálové stránky psány pomocí sady formátovacích maker. Když vyzvete člověka, aby otevřel stránku, volá to groff to přečíst soubor a vygenerovat formátovaný výstup, podle maker v souboru. Výstup je veden do méně, a pak zobrazené pro vás.

Pokud nevytváříte manuálové stránky často, je psaní jedné a ruční vkládání maker těžká práce. Vytvoření manuálové stránky, která se správně analyzuje a vypadá správně, může překonat váš cíl poskytnout stručný, ale důkladný popis vašeho příkazu.

Měli byste se soustředit na svůj obsah a ne bojovat s obskurní sadou maker.

pandoc na záchranu

The program pandoc čte soubory markdown a generuje nové v asi 40 různých značkovacích jazycích a formátech dokumentů, včetně manuálové stránky. Zcela transformuje proces psaní manuálových stránek, takže se nemusíte potýkat s hieroglyfy.

Chcete-li začít, můžete nainstalovat pandoc na Ubuntu pomocí tohoto příkazu:

sudo apt-get install pandoc

Na Fedoře potřebujete následující příkaz:

sudo dnf install pandoc

Na Manjaro zadejte:

sudo pacman -Syu pandoc

Části mužské stránky

manuálové stránky obsahují sekce, které se řídí standardní konvencí pojmenování. Sekce, které vaše manuálová stránka potřebuje, jsou diktovány propracovaností příkazu, který popisujete.

Většina manuálových stránek obsahuje minimálně tyto sekce:

Název: Název příkazu a skromný řádek, který popisuje jeho funkci.
Synopse: Stručný popis vyvolání, které může někdo použít ke spuštění programu. Ty ukazují typy akceptovaných parametrů příkazového řádku.
Popis: Popis příkazu nebo funkce.
Možnosti: Seznam možností příkazového řádku a jejich funkce.
Příklady: Některé příklady běžného použití.
Výstupní hodnoty: Možné návratové kódy a jejich význam.
Chyby: Seznam známých chyb a zvláštností. Někdy je toto doplněno (nebo nahrazeno) odkazem na nástroj pro sledování problémů projektu.
Autor: Osoba nebo lidé, kteří příkaz napsali.
Copyright: Vaše zpráva o autorských právech. Ty také obvykle zahrnují typ licence, pod kterou je program uvolněn.

Když si prohlédnete některé složitější manuálové stránky, uvidíte, že je tam také mnoho dalších sekcí. Zkuste například muž muž. Nemusíte je však zahrnout všechny – jen ty, které skutečně potřebujete. manuálové stránky nejsou místem pro slovní zásobu.

Některé další sekce, které uvidíte poměrně často, jsou:

Viz také: Další příkazy související s učivem, které by někteří považovali za užitečné nebo relevantní.
Soubory: Seznam souborů obsažených v balíčku.
Upozornění: Další body, které je třeba znát nebo na které si dát pozor.
Historie: Historie změn příkazu.

Části příručky

Linuxový manuál se skládá ze všech manuálových stránek, které jsou pak rozděleny do těchto číslovaných částí:

Spustitelné programy: Nebo příkazy shellu.
Systémová volání: Funkce poskytované jádrem.
Volání knihovny: Funkce v rámci programových knihoven.
Speciální soubory.
Formáty souborů a konvence: Například „/etc/passwd“.
Hry.
Různé: Makro balíčky a konvence, jako je groff.
Příkazy správy systému: Obvykle vyhrazené pro uživatele root.
Rutiny jádra: Ve výchozím nastavení se obvykle neinstalují.

Každá manuálová stránka musí uvádět, do které sekce patří, a musí být také uložena na příslušném místě pro tuto sekci, jak uvidíme dále. Manuálové stránky pro příkazy a nástroje patří do první sekce.

Formát mužské stránky

Formát makra groff není snadné vizuálně analyzovat. Oproti tomu markdown je hračka.

Níže je manuálová stránka v groff.

Stejná stránka je zobrazena níže v označení.

Přední záležitost

První tři řádky tvoří něco, čemu se říká přední hmota. Všechny musí začínat znakem procenta (%), bez mezer na začátku, ale s jednou za nimi, za nimiž musí následovat:

První řádek: Obsahuje název příkazu, za ním následuje část manual v závorkách bez mezer. Název se stane levou a pravou částí záhlaví manuálové stránky. Podle konvence je název příkazu psán velkými písmeny, i když najdete spoustu jiných písmen. Cokoli, co následuje za názvem příkazu a číslem sekce manuálu, se stane levou částí zápatí. Toto je vhodné použít pro číslo verze softwaru.
Druhý řádek: Jméno (jména) autora (autorů). Ty jsou zobrazeny v automaticky generované části autorů na 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ředovou částí zápatí.

název

Sekce jsou označeny řádky, které začínají znakem čísla (#), což je označení, které označuje záhlaví v markdown. Číselný znak (#) musí být prvním znakem na řádku, za ním musí následovat mezera.

Sekce názvu obsahuje elegantní jednořádkový řádek, který obsahuje název příkazu, mezeru, pomlčku (-), mezeru a potom velmi krátký popis toho, co příkaz dělá.

Synopse

Synopse obsahuje různé formáty příkazového řádku. Tento příkaz může přijmout vyhledávací vzor nebo volbu příkazového řádku. Dvě hvězdičky (**) na obou stranách názvu příkazu znamenají, že název bude na manuálové stránce zobrazen tučně. Jedna hvězdička

na obou stranách nějakého textu způsobí, že manuálová stránka jej zobrazí podtržený.

Ve výchozím nastavení po zalomení řádku následuje prázdný řádek. Chcete-li vynutit pevný konec bez prázdného řádku, můžete použít koncové zpětné lomítko ().

Popis

Popis vysvětluje, co příkaz nebo program dělá. Měl by stručně pokrýt důležité detaily. Pamatujte, že nepíšete uživatelskou příručku.

Použití dvou číselných znaků (##) na začátku řádku vytvoří nadpis druhé úrovně. Můžete je použít k rozdělení popisu na menší části.

Možnosti

Část možností obsahuje popis všech možností příkazového řádku, které lze s příkazem použít. Podle konvence jsou zobrazeny tučně, takže před a za nimi uveďte dvě hvězdičky (**). Na další řádek uveďte textový popis možností a začněte dvojtečkou (:), za kterou následuje mezera.

Pokud je popis dostatečně krátký, člověk jej zobrazí na stejném řádku jako možnost příkazového řádku. Pokud je příliš dlouhý, zobrazí se jako odsazený odstavec, který začíná na řádku pod volbou příkazového řádku.

Příklady

Část s příklady obsahuje výběr různých formátů příkazového řádku. Všimněte si, že popisné řádky začínáme dvojtečkou (:), stejně jako jsme to udělali v sekci možností.

Výstupní hodnoty

Tato část uvádí návratové hodnoty, které váš příkaz odešle zpět volajícímu procesu. Může to být shell, pokud jste jej zavolali z příkazového řádku, nebo skript, pokud jste jej spustili ze skriptu shellu. I v této sekci začínáme popisné řádky dvojtečkou (:).

Hmyz

Sekce chyb obsahuje seznam známých chyb, problémů nebo vtípků, o kterých by lidé měli vědět. U projektů s otevřeným zdrojovým kódem je běžné zde zahrnout odkaz na nástroj pro sledování problémů projektu, abyste mohli zkontrolovat stav případných chyb nebo nahlásit nové.

autorská práva

Sekce copyright obsahuje vaše prohlášení o autorských právech a obvykle popis typu licence, pod kterou je software uvolněn.

Efektivní pracovní postup

Manuálovou stránku můžete upravit ve svém oblíbeném editoru. Většina, která podporuje zvýrazňování syntaxe, si je vědoma markdownu a barvy textu pro zvýraznění nadpisů, stejně jako tučného a podtržení. To je skvělé, pokud to jde, ale nedíváte se na vykreslenou manuálovou stránku, což je skutečný důkaz v pudinku.

pandoc ms.1.md -s -t man | /usr/bin/man -l -

Otevřete okno terminálu v adresáři, který obsahuje váš soubor markdown. Po otevření v editoru pravidelně ukládejte soubor na pevný disk. Pokaždé, když tak učiníte, můžete v okně terminálu provést následující příkaz:

Jakmile tento příkaz použijete, můžete jej zopakovat stisknutím šipky nahoru a poté stisknout Enter.

Tento příkaz také vyvolá pandoc v souboru markdown (zde se nazývá „ms.1.md“):
Volba -s (samostatná) generuje úplnou manuálovou stránku shora dolů, spíše než jen nějaký text ve formátu man.

Volba -t (typ výstupu) s operátorem „man“ říká pandocu, aby vygeneroval svůj výstup ve formátu man. Neřekli jsme pandocu, aby poslal svůj výstup do souboru, takže bude odeslán na stdout.

Tento výstup také posíláme do man pomocí volby -l (místní soubor). Říká člověku, aby neprohledával databázi mužů a hledal manuálovou stránku. Místo toho by měl otevřít pojmenovaný soubor. Pokud je název souboru -, man převezme jeho vstup ze stdin.

To se scvrkává na to, že můžete uložit z vašeho editoru a stisknout Q pro zavření man, pokud běží v okně terminálu. Poté můžete stisknout šipku nahoru a poté Enter, abyste viděli vykreslenou verzi své manuálové stránky přímo v man.

Vytvoření vaší mužské stránky

pandoc ms.1.md -s -t man -o ms.1

Po dokončení manuálové stránky musíte vytvořit její konečnou verzi a poté ji nainstalovat do systému. Následující příkaz říká pandocu, aby vygeneroval manuálovou stránku s názvem „ms.1“:

Toto se řídí konvencí pojmenování manuálové stránky po příkazu, který popisuje, a připojení čísla sekce manuálu, jako by to byla přípona souboru.

manpath

Tím se vytvoří soubor „ms.1“, což je naše nová manuálová stránka. kam to dáme? Tento příkaz nám řekne, kde člověk hledá manuálové stránky:

Výsledky nám poskytují následující informace:
/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 ukazuje na „/usr/local/man.“

/usr/local/man: Zde musíme umístit naši novou manuálovou stránku.

Všimněte si, že různé sekce manuálu jsou obsaženy v jejich vlastních adresářích: man1, man2, man3 a tak dále. Pokud adresář pro sekci neexistuje, musíme jej vytvořit.

sudo mkdir /usr/local/man/man1

Za tímto účelem zadáme následující:

sudo cp ms.1 /usr/local/man/man1

Poté zkopírujeme soubor „ms.1“ do správného adresáře: man očekává, že manuálové stránky budou komprimovány, takže použijeme gzipjej zkomprimovat

sudo gzip /usr/local/man/man1/ms.1

:

sudo mandb

Chcete-li, aby člověk přidal nový soubor do své databáze, zadejte následující:

man ms

A je to! Nyní můžeme naši novou manuálovou stránku nazvat stejně jako kteroukoli jinou zadáním:

Naše nová manuálová stránka je nalezena a zobrazena.

Vypadá stejně jako jakákoli jiná manuálová stránka s tučným, podtrženým a odsazeným textem na příslušných místech.

Řádky popisu, které se hodí vedle možnosti, kterou popisují, se objeví na stejném řádku. Řádky, které jsou příliš dlouhé na to, aby se vešly, se zobrazí pod možností, kterou popisují.

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.

Pokud chceš . . .