Простая старая документация

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

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

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

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

Прочитать встроенную в программу 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
    # Дополнительная информация