2 December 2009 00:00
Одна из особенностей формата Pod - его структура. На первый взгляд, есть некоторое внешнее сходство между документацией, написанной в формате Perl5 POD, и текстом в формате Perl6 Pod. Это потому, что различия лежат в основе синтаксической структуры обоих форматов.
Синтаксическая структура Pod
Основным элементом формата Pod (как и в perl5 POD) являются директивы, используемые для определения границ блоков Pod, описания конфигурационной информации (=config) и т.д. Каждая директива начинается с символа "равно" (=) в начале строки.
Примеры директив:
=config head2 :like<head1> :formatted<I>
=begin pod
=end pod
Содержимое документа состоит из одного или нескольких блоков. Каждый блок Pod может быть определен в виде трех равнозначных формах:
- Разграниченные блоки /Delimitedblocks
- Блоки-параграфы/Paragraph blocks
- Сокращенные блоки /Abbreviated blocks
Все три формы соответственно представлены на рисунке.
Каждая из форм имеет свои границы. Все содержимое документа, находящееся вне блоков Pod, определяется спецификацией как "молчаливый" материал. Этим материалом зачастую является исходный код программ, для документирования которого предназначен Pod.
В perl5 POD блок документации начинается с первой встреченной директивы и закачивается директивой =cut. Например:
=head1 test head
Some text
=cut
Таким образом получается, что структура Perl5 POD состоит из одного типа блока с указанными правилами определения границ, где директива =cut является неотъемлемой частью и служит признаком завершения блока. После этой директивы, обработчик (parser) Perl5 POD переключается в "молчаливый" режим пока не встретит следующий символ = в начале строки.
Именно изменения в определении границ блоков документации и являются тем фундаментальным различием обоих форматов.
Новые 3 формы определения блока Pod стали эволюционным развитием Perlpod Pod от POD (Plain Old Documentation).
