Loading AI tools
Из Википедии, свободной энциклопедии
Простая старая документация (англ. Plain old documentation, сокращённо pod; близкое по смыслу к оригинальному русскому выражению — «Старая добрая документация») — простой язык разметки, применяемый для документирования языка программирования Perl.
Pod разработан как простой и ясный язык с минимально необходимым полезным синтаксисом. Из него намеренно исключены механизмы для описания шрифтов, изображений, цветов или таблиц. Хотя Pod не так выразителен, как языки вроде XML или LaTeX, авторы умышленно пожертвовали выразительностью ради простоты и удобства[1]. Основными целями разработки pod являются:
Принцип работы этого формата изложен на 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
# Дополнительная информация
Seamless Wikipedia browsing. On steroids.
Every time you click a link to Wikipedia, Wiktionary or Wikiquote in your browser's search results, it will show the modern Wikiwand interface.
Wikiwand extension is a five stars, simple, with minimum permission required to keep your browsing private, safe and transparent.