Простая старая документация ( англ. Plain old documentation , сокращённо pod ; близкое по смыслу к оригинальному русскому выражению — «Старая добрая документация») — простой язык разметки , применяемый для документирования языка программирования Perl .

Устройство

Pod разработан как простой и ясный язык с минимально необходимым полезным синтаксисом. Из него намеренно исключены механизмы для описания шрифтов, изображений, цветов или таблиц. Хотя Pod не так выразителен, как языки вроде XML или LaTeX , авторы умышленно пожертвовали выразительностью ради простоты и удобства . Основными целями разработки pod являются:

• Простота разбора
• Простота преобразования в другие форматы и языки, например в HTML или TeX
• Простота включения примеров с кодом
• Простота чтения в исходной форме, то есть без обработки программами форматирования
• Простота написания (иначе программисты не станут писать документацию!)

Принцип работы этого формата изложен на man-странице , а некоторые pod-трансляторы описаны на man-страницах , и . Хотя авторы руководства отмечают, что возможностей pod скорее всего недостаточно для написания на нём книг , фактически есть книги, написанные в расширенной версии pod. Эта расширенная версия включает в себя возможности для форматирования таблиц и подстрочных примечаний и использовалась издательством O'Reilly & Associates для производства нескольких книг о перле (наиболее известная из них это Ларри Уолла , Тома Кристиансена и Джона Орванта). Ещё одна расширенная версия pod, называемая mod, использовалась при написании книги Марка Джейсона Доминуса.

Использование встроенной в программу POD-документации

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

% perldoc program_with_pod
% perldoc perlpod

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

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

% pod2html --outfile=program.html program_with_pod

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

pod2text filename.pm > filename.txt

Пример кода

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

#!/usr/local/bin/perl

hello();

sub hello {
        print "Hello, world!\n";
}

__END__

# Пустая строка обязательна
=head1 NAME
    # Имя программы или модуля
=head1 SYNOPSIS
    # Одна строка, описывающая, что делает модуль или программа
=head1 DESCRIPTION
    # Массив документации
=head1 AUTHOR
    # Кто вы такой
=head1 BUGS
    # Что сделано неправильно
=head1 SEE ALSO
    # Дополнительная информация

Примечания