Что такое POD и как его использовать. Шпаргалка

Шпаргалка нужна не для изучения предмета, а для быстрой подсказки или использования в стиле «copy/paste». :) Так что, упреки в нераскрытости темы не принимаются. :)

Общее описание

POD можно встраивать в файлы любого типа. Можно создавать файлы, которые целиком состоят из
pod-документации.

POD-строками считаются все строки, начинающиеся со знака «=» в начале строки (без пробельных
отступов) и по строку «=cut» в начале строки (без пробельных отступов). Такие блоки пропускаются
интерпретатором, что позволяет внедрять эту документацию в любое место кода в любом количестве.

 

Директивы POD

Список директив POD

 

=headN heading

Создание заголовков заданного уровня. Остальной текст параграфа будет рассматриваться как описание заголовка.

Аналогичны заголовкам разделов и подразделов <h1>…</h1> и <h2>…</h2> в HTML.

 

=over N, =item text, =back

Элементы для создания списков. N — в элементе =over означает отступ (число в пробелах) списка от края документа.

Нумерованый список:

Маркированый список:

Именованый список:

 

=cut

Директива =cut указывает на конец любого блока pod-документации.

 

=pod

Начинает новый блок pod-документации.

 

=for X

Директивы =for, =begin и =end позволяют включать особые разделы, которые должны передаваться
в неизменном виде, но лишь определенным трансляторам. Трансляторы, которые узнают в TRANSLATOR
свое имя или псевдоним, обращают внимание на эти директивы; другие их полностью игнорируют.

Директива =for указывает, что оставшаяся часть этого абзаца предназначена конкретному транслятору.

 

=begin X, =end X

Парные директивы =begin и =end действуют аналогично =for, но вместо того, чтобы принимать
только один абзац, они рассматривают весь текст между соответствующими =begin и =end как
предназначенный для конкретного транслятора.

 

Основные элементы форматирования POD-документации

 

Стандартные блоки, включаемые в POD-документацию

=head1 NAME Имя программы или модуля.

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

=head1 DESCRIPTION Документация.

=head1 SUBROUTINES/METHODS Описание подпрограмм и методов модуля.

=head1 BUGS Что сделано неправильно, почему и будет ли исправлено в следующих версиях программы.

=head1 TODO — Что еще следует сделать.

=head1 SEE ALSO Где можно найти дополнительную информацию по модулю, по теме.

=head1 AUTHOR — Автор.

=head1 USAGE — Использование.

=head1 REQUIRED ARGUMENTS — Необходимые аргументы.

=head1 OPTIONS — Опции.

=head1 DIAGNOSTICS Выполненные диагностики и проверки, тестирование.

=head1 CONFIGURATION AND ENVIRONMENT — Конфигурация и окружение.

=head1 DEPENDENCIES — Зависимости.

=head1 INCOMPATIBILITIES — Несовместимости.

=head1 HISTORY История изменений в порядке увеличения версии.

=head1 DISCLAIMER Правовая информация. Ответственность сторон.

=head1 BUGS AND LIMITATIONS — Что сделано неправильно, почему и будет ли
исправлено в следующих версиях программы. Ограничения использования.

=head1 EXAMPLES — Примеры использования.

=head1 FREQUENTLY ASKED QUESTIONS — Часто задаваемые вопросы.

=head1 COMMON USAGE MISTAKES — Часто встречающиеся ошибки использования.

=head1 THANKS Благодарности.

=head1 COPYRIGHT

 

Типичное содержимое POD-документации для описания модуля

Дополнительные блоки, включаются по мере необходимости:

 

Типичное содержимое POD-документации для описания приложения

При необходимости добавляются:

 

Как читать POD-документацию

Как читать

Прочитать встроенную в программу POD-документацию в отформатированном виде можно с помощью
поставляемой утилиты просмотра:

Кроме того, POD-документацию очень удобно читать при просмотре исходного кода модуля.

Описание в формате POD можно преобразовать в web-страницу поставляемой в комплекте с perl утилитой:

Для преобразования документации в обычный текстовый формат, можно использовать:

 

Русскоязычная POD-документация

Если русскоязычные символы в документации отражаются неадекватно, можно изменить настройки переменных окружения. А точнее — указать, какую кодировку использовать при чтении-редактировании файлов.

Просматриваем, что у нас уже имеется:

Добавляем новую переменную:

Смотрим результат:

 

Примеры кода

POD-документация добавлена в конец файла

Программный код:

Вывод данной документации можно осуществить с помощью команды:

Вывод (что получилось, после выполнения данной команды):

 

POD-документация встроена в код

Программный код:

Вывод perldoc:

Что такое POD и как его использовать. Шпаргалка: 2 комментария

Комментарии запрещены.