Manuálové stránky z reSturcturedTextu

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.

Generování

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.

~$ rst2man foo.rst | gzip > foo.1.gz

ukázka volání příkazu rst2man

from docutils.core import publish_string
from docutils.writers.manpage import Writer

from gzip import open as zopen


def man_page(src, dst):
    with open(src, encoding="utf-8") as source:
        rst = source.read()
    with zopen(dst, 'wb') as destination:
        destination.write(publish_string(source=rst, writer=Writer()))

ukázka použití knihovny docutils v jazyce Python

Obsah

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á.

Příklad

foo
===

:manual_section: 1
:manual_group: General Commands Manual
:date: 18 Jan 2018
:subtitle: example command
:author: Ondřej Tůma
:version: 1.0.0

SYNOPSIS
--------

foo [options] [FILE]

DESCRIPTION
-----------

Foo is simple example command, which not do anything.

OPTIONS
-------

-h, --help      Show help options

:FILE:  Specifies the file to do with it anything.

FILES
-----

~/.config/foo.ini
  User personal configuration file.

/etc/foo.ini
  System configuration file.

~/.cache/foo.ini
  User personal cache file.

ENVIRONMENT
-----------

:FOO_YES:   Environment variable, which is use.

:FOO_NO:    Environment variable, which is not use.

DIAGNOSTICS
-----------

Foo command always return false, because it does not exist.

BUGS
----

If you find a bug, please report it to author of foo command.

SEE ALSO
--------

boo(1), foo(3)

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.

přílohy: foo.rst, foo.1.gz, foo.html