Создаём мануалы

Рано или поздно при написании утилиты возникает необходимость составления пользовательской документации по ней. Традиционно такой документацией является 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

Это выдаст весьма красивую man страничку. Для русской версии мануала есть некоторые особенности. Так, указание кодировки в файле должно быть обязательно. Для генерации *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 в кракозябрах. Это связано с тем, что ему не хватает юникодовых шрифтов, но педцепить из у меня так и не получилось.