Manpages#

Полезные ссылки:

https://tldp.org/HOWTO/Man-Page

С написанием UNIX мануалов есть некоторые проблемы:

Для мануалов можно использовать только те форматы, котороые поддерживает man.
Язык разметки ROFF очень плох. Его создатели, вероятно, ненавидели технических писателей.

Инструменты#

Непосредственно roff (на русском)
groff (The GNU Troff)
ronn
help2man
Любой язык разметки с дальнейшим транспилированием в ROFF.

Использование reStructuredText#

Из упрощённых языков разметки мне больше всего импонирует reStructuredText из-за своей гибкости и достаточной простоты.

Нужная нам утилита rst2man включена в пакет docutils и есть в шататных репозиториях большинства дистрибутивов.

Вот пример простейшего мануала на rST:

:Title: my_prog
:Title upper: MY_PROG
:Subtitle: my awesome programm
:Author: Me
:Copyright: \(C) 2022, Me me@example.com, GPLv3+
:Date: 2022 Jul 27
:Manual section: 1
:Version: my_prog 1.0.0

SYNOPSIS
--------

my_prog [`OPTIONS`]... [`ARGUMENTS`]...

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

Do something cool.

OPTIONS
-------

-h, --help      print help message and exit.
-v, --version   print version and exit.

SEE ALSO
--------

**man**\(1)

Конвертировать документ в ROFF можно такой командой::

rst2man my_prog.1.rst | gzip -9c > my_prog.1.gz

Следует заметить, что в итоговом документе появились не описанные в исходнике секции: NAME, AUTHOR и COPYRIGHT. Эти секции неявно добавляются при указании специальных атрибутов в начале исходного документа. Атрибуты являются стандартным элементом синтаксиса reStructuredText.

Полный список доступных атрибутов для docutils.manpage нигде нормально не описан, но его можно подглядеть прямо в исходниках пакета docutils вот здесь.

Имена атрибутов нечувствительны к регистру, а знак подчёркивания может быть заменён на пробел, т.о. имена manpage_section и Manpage section равнозначны. Рассмотрим более детально:

title: Это будет имя программы, указанное в секции NAME.
title_upper: Должен совпадать с title, но содержать имя программы в uppercase. Отображается в header line и footer line страницы.
subtitle: Подзаголовок программы в секции NAME. Обычно это очень короткое описание.
author: Отображается в секции AUTHOR.
copyright: Отображается в секции COPYRIGHT.
date: Дата отображается в footer line страницы.
manual_section: Номер раздела мануалов, добавляется в скобках к title_upper.
version: Отображается в footer line слева.

Атрибуты title, title_upper и subtitle можно заменить заголовками первого и второго уровней. Заголовки должны стоять в начале документа до объявления любых атрибутов.

Заголовок	Запись через атрибуты
======= my_prog =======	:title: my_prog :title_upper: MY_PROG
------------------- my awesome programm -------------------	:subtitle: my awesome programm