Ведение технической документации в формате Perl6’s Pod

Александр Загацкий, Витебск, Беларусь, http://zag.ru, me@zag.ru

Создание документации по программному коду, по проекту, написание руководств для конечного пользователя – неотъемлемая часть цикла создания программного обеспечения.

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

Наиболее распространенная и зачастую основная документация в проекте – это документация по программному коду. Ее пишут программисты для других программистов, а также она используется в дальнейшем системными администраторами, менеджерами и даже может быть предоставлена конечному пользователю. Эффективность ведения данной документации сильно зависит от ее интеграции со средствами разработки, от формата представления информации и, в конечном счете, от того, насколько ее создание требует отвлечения разработчика от основного процесса.

Для многих языков программирования существуют решения, упрощающие процесс документирования с помощью особого формата комментариев или средствами среды разработки. В perl5 такая система встроена и называется POD (Plain Old Documentation).

В списке технологий, приходящих с языком perl6, присутствует новый формат встроенной документации – Pod. Он является диалектом более общего формата разметки Perldoc. Но несмотря на внешнее сходство, как в названиях, так и в синтаксисе, Perldoc Pod является эволюцией POD (Plain Old Docuemtation). Новый диалект Pod, так же как и существующий формат POD, не ограничен документированием только программного кода. На нем возможно создание полноценных документов, и это позволяет сравнивать его с другими языками разметки и использовать практически повсеместно.

Наиболее распространенные инструменты и форматы разметки можно разделить на две категории: специализирующиеся на документировании кода и универсальные языки разметки.

К первой группе относятся в основном форматы, используемые т.н. генераторами документации ¹. Данные программы обрабатывают исходные коды, извлекая специально оформленные комментарии, и формируют пригодные для чтения документы. Основным их преимуществом является то, что код и его описание находятся в непосредственной близости друг от друга. Это позволяет поддерживать документацию в актуальном состоянии. Примеры таких генераторов: Javadoc, PHPDoc, Doxygen.

При большом количестве и разнообразии подобных генераторов, им свойственен также существенный недостаток: ограниченность. Основная их задача – документирование API и не более.

Ко второй группе относятся легковесные языки разметки ². Основным инструментом их создания является простой текстовый редактор или поле тестового ввода в браузере. Они легко читаются и обладают простым синтаксисом, поэтому иногда к ним применяется такое определение как “Humane Text Formats” или “Lightweight markup languages”.

C помощью данных форматов создаются руководства для конечных пользователей или документация по проекту в целом. Среди них – Markdown, reStructuredText, txt2tags, POD. Данные форматы содержат в своем синтаксисе элементы структуры документа: например заголовки разных уровней, списки.

Они встраиваются в исходные тексты программ посредством тех же комментариев, а затем извлекаются внешними программами. Особенностью POD (Plain Old Documentation) является поддержка языком программирования, благодаря чему данный формат наиболее органично встраивается в исходные тесты программ.

Основные языки обладают схожими возможностями, но некоторые из них имеют явные преимущества. Среди таких преимуществ – возможность определения таблиц, простая объектная модель документа и простота синтаксиса.

Ни один из представленных форматов не обладает всеми преимуществами одновременно. Разрабатываемый формат Perldoc Pod содержит достоинства существующих языков разметки, а также обладает уникальными, среди которых – расширяемость.

Формат POD (Plain Old Documentation) отпраздновал в 2009 году 15 лет. Новый формат Perldoc Pod готовится вместе с новой версией perl6.

Cпецификация s26, появившаяся в августе 2009 г., представляет новый формат следующим образом ⁴:

Perldoc – легкий в использовании язык разметки с простой, однозначной моделью документа.
Perldoc – поддерживает множество синтаксических диалектов, которые преобразуются в стандартные объекты модели.
Стандартный диалект Perldoc – “Pod”.

Таким образом, Pod избавился от слова “старый”.

Одна из особенностей формата Pod – его структура. На первый взгляд, есть внешнее сходство между документацией, написанной в Perl5 POD, и текстом в формате Perl6 Pod. Различия лежат в основе синтаксической структуры обоих форматов.

Основным элементом формата Pod (как и в perl5 POD) являются директивы, используемые для определения границ блоков Pod, описания конфигурационной информации (=config) и т.д. Каждая директива начинается с символа “равно” (=) в начале строки. Примеры директив:

    =config head2  :like<head1> :formatted<I>
    =begin pod
    =end pod

Содержимое документа состоит из одного или нескольких блоков. Каждый блок Pod может быть определен в виде трех равнозначных формах:

разграниченные блоки /Delimitedblocks
блоки-параграфы/Paragraph blocks
сокращенные блоки /Abbreviated blocks

Все три формы соответственно представлены на рисунке.

Рис. 1 – Формы представления блоков документации

В perl5 POD блок документации начинается с первой встреченной директивы и закачивается директивой =cut. Например:

 =head1 test head
 Some text
 =cut

Т.о. структура Perl5 POD состоит из одного типа блока с указанными правилами определения границ, где директива =cut является неотъемлемой частью и служит признаком завершения блока. После этой директивы обработчик (parser) Perl5 POD переключается в “молчаливый” режим пока не встретит следующий символ = в начале строки.

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

Новые 3 формы определения блока Pod стали эволюционным развитием Perlpod Pod от POD (Plain Old Documentation). Реализаций имеется не так уж много: