Создаём man-страницы

Рано или поздно при создании инструментов командной строки возникает необходимость составления пользовательской документации. Традиционно такой документацией является «мануал» - страница с подсказками, отображаемая по команде man. Такие страницы пишутся на специальном языке разметки, который понимают *roff программы. Но он совершенно непригоден для редактирования человеком. Существует несколько проектов, решающих эту проблему, но здесь я расскажу о POD.

POD - Plain Old Documentation специальный язык разметки, располагающийся в комментариях к программам на perl. Но его можно использовать даже если проект написан на чём-то ещё.

Рассмотрим простейший пример документации к команде mkdir, написанный на perldoc. Для начала английскую версию. Основными элементами являются заголовки:

=head1 NAME - заголовок самого высокого уровня;
=over 7 - список. Каждый новый элемент будет иметь отступ 7 символов по сравнению с основным текстом;
=item - элемент списка;
=over - конец списка.

Ещё есть несколько элементов форматирования, наиболее распространённых в документации:

I<> - italic. Наклонный текст;
B<> - bold. Жирный текст (обычно просто более яркий);
F<> - file. Обозначает путь к файлу, но его можно использовать для подчёркивания текста;
L<> - link. Ссылка;
C<> - code. Участок программного кода.

Этого вполне хватит чтобы составить приличную документацию. Иногда документацию хотелось бы иметь на русском языке. Для этого самой первой строкой нужно поставить =encoding utf-8 и писать на русском.

Теперь надо это как-то скомпилировать. Сначала преобразуем в формат *roff:


$ pod2man -c "User commands" -n mkdir -s 1 -r "GNU coreutils 8.17" en/mkdir.pod > en/mkdir.1

Рассмотрим аргументы:

-c "User commands" - заголовок мануала, который будет виден в центре страницы;
-n mkdir - имя документа, которое отображается слева и справа сверху;
-r "GNU coreutils 8.17" - название пакета, в котором лежит команда.

Чтобы посмотреть страничку достаточно ввести команду:


$ nroff -Tutf8 -mandoc en/mkdir.1 | less

Собственно, касательно простой man страницы это всё. Но если инструмент должен также работать и под Windows, то там *roff страница особо не поможет. Для этого можно конвертировать её в pdf:


groff -Tps -mandoc en/mkdir.1 > en/mkdir.ps && ps2pdf en/mkdir.ps en/mkdir.pdf && rm en/mkdir.ps

Это выдаст весьма красивую документацию. Для русской версии документа есть некоторые особенности. Так, указание кодировки в файле должно быть обязательно. Для генерации *roff файла нужно вводить:


$ pod2man --utf8 -c "User commands" -n mkdir -s 1 -r "GNU coreutils 8.17"

как видно, добавилась опция --utf8. Далее для просмотра следует ввести:


$ groff -Dutf8 -Tutf8 -mandoc ru/mkdir.1 | less

А вот с созданием pdf всё несколько сложнее. Если ввести:


$ groff -Dutf8 -Tps -mandoc ru/mkdir.1 > ru/mkdir.ps && ps2pdf ru/mkdir.ps ru/mkdir.pdf && rm ru/mkdir.ps

то groff будет ругаться на неизвестные юникодовые символы и создаст pdf в кракозябрах. Это связано с тем, что ему не хватает юникодовых шрифтов, но подцепить из у меня так и не получилось.

2012-07