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

  • Разграниченные блоки / Delimited blocks
  • Блоки-параграфы / Paragraph blocks
  • Сокращенные блоки / Abbreviated blocks

Ожидается введение еще одного типа блоков, который встроен в комментарии: 

 my $declared_thing;   #= Pod here until end of line
 sub declared_thing () {   #=[ Pod here
                              until matching
                               closing bracket
                             ]
         ...
  }

С новыми дополнениями можно ознакомится в рассылке, посвященной Perl6, по адресу: S26 - The Next Generation.

Разграниченные блоки / Delimited blocks

Разграниченные блоки имеют явно определенные границы. Для этого используются директивы =begin и =end, за каждой из которых следует имя типа блока (typename). Имена состоят из букв, цифр и символов подчеркивания, а начинаются с буквы или знака подчеркивания. Имена, состоящие целиком из символов нижнего (=begin head1) и верхнего =begin SYNOPSIS регистра, зарезервированы.

В строке с директивой =begin после имени блока следует конфигурация данного блока. Среди особенностей нового диалекта Pod - эта одна из самых замечательных. Конфигурация блока может использоваться в различных целях, в том числе и при создании расширений для Pod.

Конфигурационные параметры блока представлены в виде парной нотации в стиле Perl6 ( SYNOPSIS 02 ).

Парная нотация конфигурации блоков Pod
значениеформат определениятакже...также ..(*)
Boolean(true):key:key(1)key=>1
Boolean(false):!key:key(0)key=>0
String:key<str>:key('str')key=>'str'
List:key<1 2 3>:key[1,2,3 ]key=>[1,2,3]
Hash:key{a=>1, b=>2}-key=>{a=>1, b=>2}

(*) - последняя форма не поддерживается в реализации Perl6::Pod.

Если параметры блока не помещаются в одну строку, конфигурационный блок можно продолжить со следующей. В этом случае в начале строки ставиться символ = и пробел, далее конфигурационные параметры продолжаются.

Между директивами =begin и =end располагается содержимое блока. Сроки внутри блока могут содержать отступы, но они интерпретируются как блоки кода только в блоках =pod, =item =code и семантических блоках (например: =METHOD). То есть содержимое блока =para может отстоять от начала строки и не интерпретироваться при этом как код ( verbitim paragraph в Perl5 POD).

Синтаксис блока выглядит следующим образом: 

  =begin BLOCK_TYPE  OPTIONAL CONFIG INFO
  =                  OPTIONAL EXTRA CONFIG INFO
  BLOCK CONTENTS
  =end BLOCK_TYPE

Например: 

    =begin table  :caption<Table of Contents>
        Constants           1
        Variables           10
        Subroutines         33
        Everything else     57
    =end table

    =begin Name  :required
    =            :width(50)
    The applicant's full name
    =end Name

    =begin Contact  :optional
    The applicant's contact details
    =end Contact

Пустые строки между директивами, как это было в Perl5 POD не нужны; если они есть - то интерпретируются как часть содержимого блока. Кстати "пустыми" в Pod считаются также строки, содержащие только пробелы!

Блоки-параграфы / Paragraph blocks

Блоки параграфы начинаются с директивы =for и завершаются следующий директивой или пустой строкой ( она не считается частью блока ). После директивы =for следует имя блока и необязательные конфигурационные параметры.

Синтаксис этого типа блоков следующий: 

    =for BLOCK_TYPE  OPTIONAL CONFIG INFO
    =                OPTIONAL EXTRA CONFIG INFO
    BLOCK DATA

Примеры: 

    =for table  :caption<Table of Contents>
        Constants           1
        Variables           10
        Subroutines         33
        Everything else     57

    =for Name  :required
    =          :width(50)
    The applicant's full name

    =for Contact  :optional   
    The applicant's contact details

Сокращенные блоки / Abbreviated blocks

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

Синтаксис блока следующий: 

    =BLOCK_TYPE  BLOCK DATA
    MORE BLOCK DATA

Пример: 

    =table
        Constants           1
        Variables           10
        Subroutines         33
        Everything else     57

    =Name     The applicant's full name
    =Contact  The applicant's contact details

Этот тип блока подходит для случаев, когда можно обойтись без конфигурирования блока. Иначе придется воспользоваться =for или =begin/=end директивами.

Равнозначность стилевых блоков

Описанные выше типы блоков одинаково представлены во внутренней структуре документа. То есть если имя типа блока - параграф (=para), то он остается параграфом независимо от формы его описания.

Практически это означает, что приведенные ниже блоки: 

 =begin para
 Text
 =end para

 =for para text

 =para text

при конвертации в html будут преобразованы в один и тот же текст: 

    <p>text</p>

Если тип блока таблица, то она останется ею в любом случае.