Я хотел бы рассказать о случае из моего опыта разработчика, когда POD существенно помог мне.

Работал я в одном стартапе. Это было относительно давно, тем не менее эта история может кому-то пригодится. Как и в любом стартапе, в самом начале его существования отсутствует какая либо жесткая субординация (как впрочем и бюрократия). С одной стороны в самом начале проекта необходима максимальная отдача от всех, с другой стороны в небольшом коллективе граница между руководителями и подчиненными весьма призрачны. Так же нет четкой границы в обязанностях.

Я начинал работу в таком стартапе как разработчик некоего интерфейса для партнеров проекта (пусть это будет "панель управления").

В стартапе была небольшая иерархия и сразу же после моего руководителя шел генеральный руководитель - Антон (имя изменено). Коллектив был небольшой и по большей части в те года молодой и малоопытный. Было увлекательно вести разработку непосредственно своего проекта и участвовать в решении архитектурных проблем остальных (мой админский опыт способствовал этому).

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

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

Это вполне себе нормальная ситуация. Для начальной реализации мне достаточно было подойти к разработчикам обоих проектов и узнать технические детали их баз данных. Первый прототип был готов в указанные сроки и был продемонстрирован Антону. Здесь начались первые сложности. В подготовленном приложении обнаружились неточности в реализации логики и у Антона появились новые идеи (!).

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

Стоит отметить, что все это время я делал заметки в блокноте, отмечая основные моменты в процессе беседы. Каждой раз я начинал записи на отдельном чистом листе. После пары встреч, я стал замечать, что некоторые замечания Антона начинают противоречить ранее сформулированным задачам. Тем временем из казалось бы простой задачи на одну страницу блокнота, процесс увеличился на десяток исписанных страниц A4.

Так как, для реализация логики необходимы были данные из нескольких независимых проектов, это вносило еще один тормозящий фактор. Дело в том, что проекты быстро развивались и при этом менялась структура хранилища одного из них. Попросту говоря, мои SQL запросы переставали работать.

Все вместе это приводило к возникновению задач по поддержке работоспособности уже созданного кода и вместе с изменчивым мнением Антона грозило перерасти в довольно некрасивую ситуацию.

Именно в этот момент и был составлен документ Технического Задания! В него я перенес все задачи из блокнота по итогам последних встреч, а также сделал отдельный раздел, в котором в виде списка перечислил последовательность действий программы. Приведу пример одного из такого пункта:

     =item * Фильтрация по рубрикам (filter_by_rubrik)

     Фильтр по рубрикам. На вход передается идентификатор произведения (bookid) и 
     его рубрика является фильтром для всех остальных книг.

     * запрос на получение идентификатора рубрики (база произведений)

     ______________________________________________________________

     ______________________________________________________________

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

Теперь я распечатывал перед каждой встречей с Антоном последнюю копию этого документа и отмечал замечания по ходу беседы непосредственно в нем. Этот документ стал предметом обсуждения!

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

Конечно, не случайно в качестве формата технического задания был выбран POD, но на его месте мог быть любой другой формат разметки. Тем не менее, я благодарен формату Perl 5 POD за его помощь, хоть и пишу сейчас Технические Задания (как и текст этого поста) в формате Perl 6 Pod !

Разновидностью кода замещения P<> является код форматирования A<>. Он замещается содержимым именованного псевдонима или объекта, указанных внутри ограничителей. Например:

    =alias PROGNAME    Earl Irradiatem Eventually
    =alias VENDOR      4D Kingdoms
    =alias TERMS_URL   L<http://www.4dk.com/eie>

    The use of A<PROGNAME> is subject to the terms and conditions
    laid out by A<VENDOR>, as specified at A<TERMS_URL>.

Любой из объектов Perl 6, доступный на этапе компиляции и содержащий сигил, автоматически становится доступным для подстановки по его имени. Также все объекты, которые не являются строковыми типами, в режиме подготовки документации преобразуются в строки посредством неявного вызова метода .perl.

Так, например, документ может ссылаться на имя своего файла - A<$?FILE>, на подпрограмму, внутри которой размещен блок Pod - A<$?ROUTINE> или на текущий класс A<$?CLASS> ^[1].

Аналогично, значение любой программной константы определенной с сигилом может быть легко вставлено в документацию:

    # Actual code...
    constant $GROWTH_RATE of Num where 0..* = 1.6;
    =pod
    =head4 Standard Growth Rate
    The standard growth rate is assumed to be A<$GROWTH_RATE>.

Для подобных объектов возможны вызовы константных (non-mutating) методов. Так например, в документации можно вставить сигнатуру подпрограммы (A<$?ROUTINE.signature>) или тип константы (A<$GROWTH_RATE.WHAT>).

На странице конвертера "Perl 6 Pod to HTML" доступен пример кода форматирования A.

По итогам выступления на YAPC::Russia отметил следующие моменты:

Возможна ли фильтрация блоков документации ?

В спецификации есть момент, описывающий способ решения подобной задачи. Для этого используется код форматирования Z<> (inline comment). Содержимое этого блока является комментарием и удаляется трансляторами при обработке. Однако, содержимое может служить признаком, конфиденциальности, если в нем содержится например слово "КОНФИДИЦИАЛЬНО". Таким образом, при обработке блоки, удовлетворяющие условию /КОНФИДИЦИАЛЬНО/, могут быть пропущены.

 class Widget is Bauble
    {
        has $.things; #= a collection of other stuff
        #={ Z<КОНФИДИЦИАЛЬНО>
            This variable needs to be replaced for political reasons
        }
    }

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

 =for para :!public
 Данный параграф недоступен для публикации

Фильтрация блоков происходит при обработке пользовательской директивы =Include. Реализация этого блока находится в библиотеке Perl6::Pod::Lib. Синтаксис параметров фильтрации следующий:

 =Include file:api.pod(para :public)

Данный блок вставит в указанное место только блоки para с свойством public из файла api.pod.

Использование Pod в Perl 5

Модуль Perl6::Pod представляет собой SourceFilter и позволяет использовать блоки Pod в тексте программ Perl 5. Конечно же парсер не позволяет использовать блоки-деклараторы и подобные фитчи Pod, привязанные к грамматике Perl 6.

Чтобы писать документацию в формате Pod достаточно указать в начале программы:

  use Perl6::Pod;

Единственный недостаток использования этого модуля: он недостаточно хорошо протестирован.

Создание презентаций в Perl 6 Pod

Библиотека Perl6-Pod-Slide позволяет создавать презентации, используя Perl 6 Pod. Принцип ее работы прост: текст Pod транслируется в Tex, а затем "родными" средствами Tex преобразуется в Pdf. Делается это в два шага:

 pod6slide < tech_docs.pod > tech_docs.tex
 pdflatex tech_docs.tex

Также хотелось бы отметить качественный уровень конференции этого года. Были приглашены активные разрабочики Perl 6: Джонатан Вортингтон (Jonathan Worthington) и Карл Мэсак (Carl Masak).

Благодаря яндексовцам открыл для себя psgi.streaming. С учетом этой возможности PSGI стал применим для моих практических задач.

На сегодня, в проекте создания книги, посвященной Perl 6 ^[1], произошло хоть и небольшое, но на мой взгляд знаковое событие - в книге появилась первая авторская глава "Формат Pod". В ее основу легли мои материалы опубликованные на страницах блога http://zag.ru. Публикации, описывающие формат Perl 6 Pod, я вел по мере реализации спецификации ^[2]. Однако собранные в виде главы книги они более удобны для изучения.

Тем не менее, знаковость появления новой главы мне видится в другом. До этого основным источником для книги служили переводные материалы из английской книги "Using Perl 6", которую создают разработчики Rakudo, реализации Perl 6 на Parrot. Авторская глава - признак того, что у книги "Все о Perl 6" есть шансы стать наиболее полным источником разнообразных материалов о языке.

Конечно же это не значит, что перевод книги "Using Perl 6" перейдет на второй план. Ничуть. Хоть книга от разработчиков еще находится в стадии создания и есть незавершенные главы, но более-менее стабильные главы по прежнему будут переводится на русский. Так к примеру, на прошедшем хакантоне я приступил к переводу главы, посвященной классам и объектам. И впереди еще более интересные главы.

Собрав материалы по интересующей меня тематике, а именно по Perl 6 Pod, в виде главы книги, я получил определенные плюсы:

• систематизировал свои результаты в этой области
• опубликовал их и тем самым получил инструмент их распространения
• поделился опытом с коллегами

Идея, которую хотелось бы высказать, следующая: Книга "Все о Perl 6" не цель, а инструмент. Инструмент для разработчиков чтобы поделиться опытом, а для читателей - способ получить наиболее полную информацию о языке и сократить время на его изучение.

Эта книга также инструмент распространения формата Perl 6 Pod. Поэтому она для меня значима, как первая в мире книга в формате Perl 6 Pod. Познакомиться с этим форматом можно в главе "Формат Pod".

Perl 6 Pod представляет собой гибкий и расширяемый язык разметки. В первую очередь он полезен для ведения документации: как технической (описание API, технические задания ), так и пользовательской: например, руководства и даже книги.

Мои первые руководства я создавал для пользователей компьютерной лаборатории. В те времена (в середине 90x) для этих целей применялся Microsoft Word. Позднее я использовал для создания документов HTML, Tex и docbook. В дальнейшем основным форматом, который я стал использовать повсеместно, был Perl 5 POD ^[1]. Возможно, причиной тому стала его интеграция с языком Perl. Это позволило создавать качественную документацию непосредственно во время разработки, а так же поддерживать ее в актуальном состоянии. Конечно же, эта документация была по программному коду.

Тем не менее, Perl 5 POD был удовлетворительным форматом и для создания руководств. Для полного счастья не хватало поддержки изображений, таблиц. Эти неудобства устранялись созданием специализированного парсера, который особым образом обрабатывал POD. Таким образом создавался некий подсинтаксис POD и, как следствие, подобная документация могла быть обработана только этим особым парсером.

В новом Perl 6 Pod ^[2], все описанные ограничения были устранены. Данный формат стал лаконичнее, появились таблицы и самое главное - расширяемость. Благодаря последней особенности в документах Pod можно реализовать любые собственные сущности: например, изображения. Хорошим примером может служить исходный код этой статьи ^[3].

Рассказать о данном формате я планирую на следующих ближайших мероприятиях:

• YAPC::Russia 2011 "May Perl + Perl Mova", 13-15 мая, Москва. ^[4]
• DevConf 2011, 4 Июня 2011, Москва. ^[5]
• Lvee 2011, 30 июня, Гродно. ^[6]
• YAPC::Europe 2011 "Modern Perl",15-17 августа, Рига. ^[7]

Помимо описания основных деталей формата Perl 6 Pod, также расскажу для решения каких задач я его использую.

После "судного" дня ^[1], меня преследует постоянное чувство беспокойства. Почему-то вдруг стал, для себя замечать, что некоторые новости заставляют задуматься о сохранности моих персональных данных.

Например, сегодняшнее сообщение на Techcrunch, про покупку сервиса Delicious ^[2]. А ведь если этот сервис закроют так же внезапно, как например в том году cliqset.com ^[3], я лишусь моих закладок в одночасье.

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

  Dear Alex,
  We are introducing a new and improved Friendster site in the coming weeks. As part of this change, we will remove a number of social networking functions in Friendster. This includes your existing account profile, photos, messages, blogs, and shoutouts. However, your list of friends will be preserved, along with your basic profile information.
  We understand that your photos, blogs and other private data may be important to you. An application is available in the "Apps" section of the site, until May 31st 2011, to help you download or export them securely to third party sites, such as Flickr or Multiply. The application is available here.

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

Среди проектов, одобренных для GSofc 2011 ^[1], хотел бы отметить пару.

• Standardization of core documentation parsing tools ^[2]

  Задача, предусматривает замену устаревшего Pod::Parser на Pod::Simple в утилитах из базовой поставки Perl 5. Данный проект касается Perl 5 POD.

• Pod parser for Rakudo ^[3].

  По данному проекту ожидается создание встроенного в Rakudo парсера Perl 6 Pod. Благодаря этому часть документации будет доступна из программного кода, как и предполагает Synopsis 26 ^[4] в разделе описания блоков-деклараторов (Declarator blocks).

  Пример такого блока:

      my $chainsaw;        #= This text stored in C<$chainsaw.WHY>
      sub fu (             #= This text stored in C<&fu.WHY>
          Any     $bar,    #= This text stored in C<$bar.WHY>
          Mode    :$baz,   #= This text stored in C<$baz.WHY>
          Context :$the_context_in_which_we_fu?
                           #= This stored in C<$the_context_in_which_we_fu.WHY>
      ) { ... }

  Программа сможет менять свое поведение в зависимости от того, что написано в документации по ней :-) ( почему бы и нет ? ).

Благодаря наводке от @bacek, прочитал переписку-обсуждение ^[5], посвященную реализации Pod на уровне Parrot VM.

От себя добавлю, что в ранних редакциях Synopsis 26, формат Pod преподносился как диалект более общего языка разметки - Perldoc. И здесь был намек, что для каждого языка, работающего поверх Parrot, будет свой диалект (сугубо мое предположение). Возможно принцип "все простое должно оставаться простым" победил и в спецификации оставили определение Pod, как языка разметки для Perl 6.

Для формата Pod, используемого в Perl 6, отсутствует оригинальная или эталонная реализация. Более того, этот формат, как и сам Perl 6, существует в виде спецификации: Synopsis 26 ^[1]. Сама спецификация написана в формате Pod и может использоваться для проверки реализаций на соответствие ей :-).

Создание спецификации датировано 9 апреля 2005 года, а последняя редакция - 31 июля 2010. Автор спецификации - Дамиан Конвей (Damian Conway). Он же автор первой реализации на языке Perl 5.

На сегодня данный формат стабилен и есть некоторое количество его реализаций.

• Perl6::Perldoc ^[2]

  Эта первая реализация на Perl 5, созданная автором спецификации Дамианом Конвеем.

  Последняя версия вышла почти 4 года назад. Однако в начале этого месяца вышло обновление в виде DEVELOPER версии. Поэтому есть шанс, что реализация будет развиваться.

• Perl6::Pod ^[3]

  Моя собственная реализация этого формата на языке Perl 5. О ее статусе можно прочитать на страницах моего блога ^[4].

  На мой субъективный взгляд, она является самой полной из существующих реализаций.

• http://github.com/perl6/perl6-examples/blob/master/lib/Pod/Parser.pm ^[5]

  Эта первая из известных мне и единственная до недавнего времени, реализация на Perl 6. Она была написана, во времена, когда еще не существовало стабильной версии Perl 6. Видимо отсутствие стабильности стало причиной ее заморозки. Автор - Martin Berends.

• SUPERNOVA ^[6]

  Совсем недавно выложенная в открытый доступ ^[7] реализация на Perl 6. Данная реализация находится в самом начале разработки. Она доступна на GitHub.

Развитие Perl 6 Pod

Сам формат Pod в некоторый частях спецификации подразумевает тесную интеграцию с грамматикой Perl 6 (например, "Блоки деклараторы"). Поэтому полная реализация этого формата возможна, скорее всего, только на Perl 6.

Тем не менее интерес к этому формату растет. Подтверждением может служить тот факт, что для участия в Google Summer of Code 2011 представлены два независимых предложения:

• от Perl Foundation ^[8]

     Pod parser for Rakudo
     Perl 6 has a built-in documentation format named 'Pod'. Rakudo currently only recognizes the begin and end of such Pod sections, and ignores them otherwise.
   A student could write a parser for Pod (or a subset of Pod), and make the parse tree available both for accessing it from withing Perl 6 objects and for redering it in other formats (plain text, html, latex, markdown, ...)
   See the Pod specification in S26
   Possible mentors: Moritz Lenz, Carl Masak

• Parrot Foundation ^[9]

      POD parser
      Difficulty: 1/5
      Links of Interest:  NONE, please add some
      Possible Mentors: UNKNOWN, please volunteer!
      Details: Implement a library or tool to parse POD documentation from standalone .pod files and code files containing intermittent POD. The successful project should be able to translate POD documentation into other formats such as LaTeX, HTML, man pages, raw text, or others. Special focus should be on both compliance with the Perl 6 POD specification (Synopsis 26 - Documentation) and interoperability with other HLLs besides Perl 6. The successful project will have a system with pluggable backends for outputting documentation in the formats listed above and others.
      Expected Deliverables: UNKNOWN, Please list what the deliverables will be