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

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

Устройство

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-документации

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

Примечания

1. ↑ ^{1 2} Ларри Уолл, Том Кристиансен, Джон Орвант Программирование на Perl = Programming Perl. — «Символ-Плюс», 2010. — С. 686-703. — ISBN 5-93286-020-0
2. ↑ «The Pod format is not necessarily sufficient for writing a book»