Як зробити man-сторінку для своєї програми

Блог про Linux, Bash та інші інформаційні технології

man-сторінку
Коли ви збираєте свій пакет із програмою або якимись даними, ви можете включити до складу пакету man-сторінку, в якій буде міститися інформація про те, для чого ваша програма призначена, які у неї є опції, опис опцій роботи, кодів повернення тощо. І, звичайно ж, там ви можете вказати свої контакти, щоб користувачі могли з вами зв'язатися, якщо знайшли якусь помилку або у них є ідеї про те, як програму можна було б поліпшити.

В операційних системах класу Unix/Linux man є стандартною програмою, яка використовується досить часто. Погодьтеся, зручно дати одну команду і подивитися інформацію про об'єкт операційної системи, що цікавить, та ще й у структурованому вигляді.

Давайте подивимося, як швидко створити свою man-сторінку, яку потім можна розмістити в системі та подивитися інформацію за допомогою команди man.

Файл man-сторінки має свій певний формат.

Перший рядок має такий вигляд:

Рядок, який тут вказується, це символ, що означає препроцесор. Можливі значення:

e - eqn g - grap p - pic t - tbl v - vgrind r - refer

Виберемо як препроцесор tbl, тоді перший рядок у нас має виглядати так:

Потім нам треба створити заголовок із наступними полями:

— Назвою програми та номером розділу, в якому знаходиться сторінка (будуть показані в першому рядку зліва і справа та в останньому рядку праворуч), — Датою створення документації (буде показана в останньому рядку посередині) — Повною назвою програми включаючи версію (буде показано в останньому рядку зліва) — Назва, яка буде показана в першому рядку man-сторінкипосередині

Тепер можна вказати імена необхідних розділів з цього списку: НАЗВА (NAME), СИНТАКСИС (SYNOPSIS), НАЛАШТУВАННЯ (CONFIGURATION), ОПИС (DESCRIPTION), ПАРАМЕТРИ (OPTIONS), КОД ВИХОДУ (EXIT STATUS), ПОВЕРНЕННЯ, ПОВЕРНЕННЯ, (ERRORS), ОКРУЖЕННЯ (ENVIRONMENT), ФАЙЛИ (FILES), ВЕРСІЇ (VERSIONS), ПОГОДЖУЄТЬСЯ З (CONFORMING TO), ЗАУВАЖЕННЯ (NOTES), ПОМИЛКИ (BUGS), ПРИКЛАД (EXAMPLE), АВТОРИ (AUTHORS) ALSO).

Назви розділів зазначаються таким чином:

Наступне, що потрібно зробити, - це виділення жирним. Ось як це робиться:

\fB - font bold, \fR - font regular

Ще одна команда нам знадобиться для пропуску рядка

Для зсуву вправо або для створення відступу нам знадобиться команда

А для повернення назад на ту саму позицію інша команда

І тепер ви вже можете створити сторінку посібників, яка включатиме інформацію про вашу програму. Ось таку:

Тепер перейменуємо файл на «myprogram.8», оскільки сторінка буде розміщуватися в 8 розділі, і стиснемо її програмою gzip

І помістимо до директорії /usr/share/man/man8. Розміщення в потрібній директорії можна реалізувати або під час встановлення пакета, або під час встановлення з вихідних кодів під час виконання скрипта make.

І останнє, що потрібно зробити – це дати команду

Ви побачите ось таку сторінку:

Ось, власне, і все. Як бачите, вийшло дуже швидко.