Одна из особенностей формата Pod - его структура. На первый взгляд, есть некоторое внешнее сходство между документацией, написанной в формате Perl5 POD, и текстом в формате Perl6 Pod. Это потому, что различия лежат в основе синтаксической структуры обоих форматов.

Синтаксическая структура Pod

Основным элементом формата Pod (как и в perl5 POD) являются директивы, используемые для определения границ блоков Pod, описания конфигурационной информации (=config) и т.д. Каждая директива начинается с символа "равно" (=) в начале строки.

Примеры директив:

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

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

Все три формы соответственно представлены на рисунке. 8a4465b8deb811debb70cf84fa0cbd7f Подробнее о каждой будет рассказано немного ниже.

Каждая из форм имеет свои границы. Все содержимое документа, находящееся вне блоков Pod, определяется спецификацией как "молчаливый" материал. Этим материалом зачастую является исходный код программ, для документирования которого предназначен Pod.

В perl5 POD блок документации начинается с первой встреченной директивы и закачивается директивой =cut. Например:

est head

   Some text
    

Таким образом получается, что структура Perl5 POD состоит из одного типа блока с указанными правилами определения границ, где директива =cut является неотъемлемой частью и служит признаком завершения блока. После этой директивы, обработчик (parser) Perl5 POD переключается в "молчаливый" режим пока не встретит следующий символ = в начале строки.

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

a378c7f4deb811deb8ed0b7bfa0cbd7f

Новые 3 формы определения блока Pod стали эволюционным развитием Perlpod Pod от POD (Plain Old Documentation).