Основной структурной единицей нового диалекта 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>
Если тип блока таблица, то она останется ею в любом случае.
