Статус реализации Perl6::Pod

Вместе с Perl 6, на смену используемому в Perl 5 POD, приходит новый формат Pod. Ему посвящен Synopsis 26 ^[1].

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

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

• Блоки деклараторы (Declarator blocks)

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

  Идея этого блока, появившегося в последней редакции Synopsis26 замечательна: сделать документирование кода проще, приблизив текст описания как можно ближе к объекту документирования.

  #= Base class for comms necromancy hierarchy
      class Magic::Necrotelecomnicon {
          has $.elemental;  #= Source of all power
          has $!true_name;  #  Source of all self-protection (not documented)
  

  method cast(Spell $s)
          #= Initiate a specified spell normally
          {
              do_raw_magic($s);
          }
  

  Как видно из примера, идея похожа на документацию, встраиваемую в виде комментариев ( а именно Doxygen ^[2]).

• Конфигурационный параметр блока :margin

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

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

   sub demo {
       B<say> 'Hello R<name>';
   }
  

  В приведенном примере, параметр :allow разрешает использовать только два кода форматирования внутри блока =code.

  Так вот, остался нереализованным последний из предусмотренных спецификацией параметр :margin. Он позволяет определить символ явного отступа.

     =head1 Indenting Pod blocks
     =begin para :margin<|>
              |This text is flush with the (virtual) left margin of
              |the Pod block because that margin is explicitly marked
              |by the C<|>, as specified by the block's C<:margin<|>> option.
     =end para
  

  Отступ вместе с символом | удаляется в выходном формате.

• Подключаемые расширения с помощью директивы DOC

  На смену существовавшей в прежних редакциях директивы =use, пришла директива Perl 6 DOC. Подразумевается, что подключение расширений, трансляторов будет производиться в самом документе. Например:

  DOC INIT {
          use Pod6::Eiffelish::Long;
          say eiffelish_long($=POD);
          exit;
      }
  

  Это конечно осложняет использование Pod вне Perl 6. Я попросил автора спецификации, рассмотреть возможность оставить в спецификации директиву =use.

• Семантические блоки DATA, END

  Остались для реализации блоки DATA, END.

• Директива =encoding

  Директива служит для указания кодировки следующего за ней текста.

  Например:

  =encoding ShiftJIS
  

  =encoding Macintosh
  

  =encoding KOI8-R
  

Вот и все, по большому счету, существенные белые пятна в реализации. Не исключено, что еще что-то я упустил.

Текущая реализация Perl 6 Pod доступна на CPAN ^[3].

Для желающих попробовать создать текст в этом формате существует онлайн конвертер "Perl 6 Pod to HTML". Он также позволяет сформировать ссылку на введенный в редакторе Pod с помощью кнопки "Generate URL". Эта функция полезна также, когда необходимо указать на ошибку или поделиться Pod.