суббота, 28 июля 2012 г.

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

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


Комментариев нет:

Отправить комментарий