Как сделать man-страницу для своей программы

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

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

Давайте посмотрим, как быстро создать свою man-страничку, которую потом можно разместить в системе и посмотреть информацию при помощи команды man.

Файл man-странички имеет свой определенный формат.

Первая строка имеет такой вид:

'\" <строка>

Строка, которая здесь указывается, это символ, обозначающий препроцессор. Возможные значения:

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

Выберем в качестве препроцессора tbl, тогда первая строчка у нас должна выглядеть так:

'\" t

Затем нам надо создать заголовок со следующими полями:

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

.TH "MYPROGRAM" "8" "01\ \&JULY\ \&2015" "MYPROGRAM 1.0.0" "MYPROGRAM"

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

Названия разделов указываться следующим образом:

.SH "NAME"

Следующее, что нужно сделать — это выделение жирным. Вот как это делается:

\fB<текст>\fR

\fB — font bold, \fR — font regular

Еще одна команда нам понадобится для пропуска строчки

.PP

Для сдвига вправо, или для создания отступа, нам понадобится команда

.RS <количество-символов>

А для возврата обратно на ту же позицию другая команда

.RE

И теперь вы уже можете создать страницу руководств, которая будет включать информацию о вашей программе. Вот такую:

'\" t

.TH "MYPROGRAM" "8" "01\ \&JULY\ \&2015" "MYPROGRAM 1.0.0" "MYPROGRAM1"

.SH "NAME"
myprogram - some program that does cool stuff
.SH "SYNOPSIS"
\fBmyprogram\fR [\fB--help\fR]
\fBmyprogram\fR [\fB--version\fR]
.SH "DESCRIPTION"
\fBmyprogram\fR is a simple program that make some really cool stuff. I didn't deside what exactly yet, but it will be awesome, trust me.
.SH "OPTIONS"
\fB--help\fR
.RS 4
Show help
.RE
.PP
\fB--version\fR
.RS 4
Show program version
.RE
.SH "AUTHORS"
Cool programmer <cool.programmer@coolmail.com>

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

gzip myprogram.8

И поместим в директорию /usr/share/man/man8. Размещение в нужной директории можно реализовать либо при установке пакета, либо при установке из исходных кодов во время выполнения скрипта make.

И последнее, что нужно сделать — это дать команду

man myprogram

Вы увидите вот такую страничку:

MYPROGRAM(8)                      MYPROGRAM1                      MYPROGRAM(8)

NAME
       myprogram - some program that does cool stuff

SYNOPSIS
       myprogram [--help] myprogram [--version]

DESCRIPTION
       myprogram  is  a  simple  program  that  make some really cool stuff. I
       didn't deside what exactly yet, but it will be awesome, trust me.

OPTIONS
       --help
           Show help

       --version
           Show program version

AUTHORS
       Cool programmer <cool.programmer@coolmail.com>

MYPROGRAM 1.0.0                  01 JULY 2015                     MYPROGRAM(8)

Вот, собственно, и всё. Как видите, получилось очень быстро.

Похожие посты: