Статус реализации 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 {
            say 'Hello name';
        }
       =end code
    
    В приведенном примере, параметр :allow разрешает использовать только два кода форматирования внутри блока =code.
    
    Так вот, остался нереализованным последний из предусмотренных спецификацией параметр :margin. Он позволяет определить символ явного отступа.
    
    =begin code
       =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 |, as specified by the block's :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

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

    Например:

    ShiftJIS

    Macintosh

    KOI8-R

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

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

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

[1] Спецификация формата Pod (Synopsis 26 ).https://github.com/zag/specs/raw/master/S26-documentation.pod

[2] Встраиваемая документация в виде комментариев Doxygen. http://en.wikipedia.org/wiki/Doxygen

[3] Реализация Perl 6 Pod на Perl 5. http://search.cpan.org/dist/Perl6-Pod/

All Articles