Загружаемые модули

Механизм, с помощью которого можно расширить синтаксис, семантику а так же содержимое документации, реализуется посредством директивы =use.

Данная директива дает указание Perldoc парсеру загрузить соответствующий модуль в указанное место. В случае неуспеха произойдет исключительная ситуация с сообщением об ошибке.

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

Директива =use может использована как с указанием имени модуля, так и с указанием URI:

    =use MODULE_NAME OPTIONAL CONFIG DATA
    =                 OPTIONAL EXTRA CONFIG DATA
    =use URI

В случае использования URI указанный адрес интерпретируется как источник Pod документации для включения в документ в месте использования директивы.

Примеры использования директивы =use:

    =use Perldoc::Plugin::Image  :Jpeg  prefix=>'http://dev.perl.org'
    =use file:/full/path/spec/Pod/Insertion/Name.pod
    =use http://www.website.com/Pod/Insertion/Name.pod

Для явного указания на документацию вместо программного модуля, используется префикс pod::

    =use pod:Some::Other::Module

Для загрузки модуля - perl6::

    =use perl6:New::Perldoc::Subclass

Именованные блоки

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

    =begin Xhtml
    <object type="video/quicktime" data="onion.mov">
    =end Xhtml

или

    =Image http://www.perlfoundation.org/images/perl_logo_32x104.png

Загрузка модулей для обработки производится с помощью директивы =use. Если не определен модуль для обработки такого блока он игнорируется. Имена всех блоков, состоящие исключительно из заглавных или строчных букв зарезервированы.

Определенные пользователем коды форматирования

Для расширения функционала кодов форматирования используется код M. Формат данного кода подразумевает указание имени блока и данных.

Пример:

 =use Perldoc::TT
 =head1 Overview of the M<TT: $CLASSNAME > class
 (version M<TT: $VERSION>)
 
 M<TT: get_description($CLASSNAME) >

Код форматирования M является строковой формой именованных блоков. Если не определен обработчик (не загружен с помощью =use), данные после двоеточия интерпретируются как обычный текст.