Простая старая документация
Простая старая документация (англ. Plain old documentation, сокращённо pod; близкое по смыслу к оригинальному русскому выражению — «Старая добрая документация») — простой язык разметки, применяемый для документирования языка программирования Perl.
Содержание
Устройство
Pod разработан как простой и ясный язык с минимально необходимым полезным синтаксисом. Из него намеренно исключены механизмы для описания шрифтов, изображений, цветов или таблиц. Хотя Pod не так выразителен, как языки вроде XML или LaTeX, авторы умышленно пожертвовали выразительностью ради простоты и удобства[1]. Основными целями разработки pod являются:
- Простота разбора
- Простота преобразования в другие форматы и языки, например в HTML или TeX
- Простота включения примеров с кодом
- Простота чтения в исходной форме, то есть без обработки программами форматирования
- Простота написания (иначе программисты не станут писать документацию!)
Принцип работы этого формата изложен на man-странице [perldoc.perl.org/perlpod.html perlpod], а некоторые pod-трансляторы описаны на man-страницах [perldoc.perl.org/pod2man.html pod2man], [perldoc.perl.org/pod2html.html pod2html] и [perldoc.perl.org/pod2text.html pod2text]. Хотя авторы руководства [perldoc.perl.org/perlpod.html 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 SEE ALSO
# Дополнительная информацияНапишите отзыв о статье "Простая старая документация"
Примечания
- ↑ 1 2 Ларри Уолл, Том Кристиансен, Джон Орвант. Программирование на Perl = Programming Perl. — «Символ-Плюс», 2010. — С. 686-703. — ISBN 5-93286-020-0.
- ↑ [perldoc.perl.org/perlpod.html «The Pod format is not necessarily sufficient for writing a book»]
| ||||||||||||||
Отрывок, характеризующий Простая старая документация
И полковой командир, оглядываясь на адъютанта, своею вздрагивающею походкой направился к полку. Видно было, что его раздражение ему самому понравилось, и что он, пройдясь по полку, хотел найти еще предлог своему гневу. Оборвав одного офицера за невычищенный знак, другого за неправильность ряда, он подошел к 3 й роте.– Кааак стоишь? Где нога? Нога где? – закричал полковой командир с выражением страдания в голосе, еще человек за пять не доходя до Долохова, одетого в синеватую шинель.
Долохов медленно выпрямил согнутую ногу и прямо, своим светлым и наглым взглядом, посмотрел в лицо генерала.
– Зачем синяя шинель? Долой… Фельдфебель! Переодеть его… дря… – Он не успел договорить.
– Генерал, я обязан исполнять приказания, но не обязан переносить… – поспешно сказал Долохов.
– Во фронте не разговаривать!… Не разговаривать, не разговаривать!…
– Не обязан переносить оскорбления, – громко, звучно договорил Долохов.
Глаза генерала и солдата встретились. Генерал замолчал, сердито оттягивая книзу тугой шарф.
– Извольте переодеться, прошу вас, – сказал он, отходя.
– Едет! – закричал в это время махальный.
Полковой командир, покраснел, подбежал к лошади, дрожащими руками взялся за стремя, перекинул тело, оправился, вынул шпагу и с счастливым, решительным лицом, набок раскрыв рот, приготовился крикнуть. Полк встрепенулся, как оправляющаяся птица, и замер.
– Смир р р р на! – закричал полковой командир потрясающим душу голосом, радостным для себя, строгим в отношении к полку и приветливым в отношении к подъезжающему начальнику.
По широкой, обсаженной деревьями, большой, бесшоссейной дороге, слегка погромыхивая рессорами, шибкою рысью ехала высокая голубая венская коляска цугом. За коляской скакали свита и конвой кроатов. Подле Кутузова сидел австрийский генерал в странном, среди черных русских, белом мундире. Коляска остановилась у полка. Кутузов и австрийский генерал о чем то тихо говорили, и Кутузов слегка улыбнулся, в то время как, тяжело ступая, он опускал ногу с подножки, точно как будто и не было этих 2 000 людей, которые не дыша смотрели на него и на полкового командира.
Раздался крик команды, опять полк звеня дрогнул, сделав на караул. В мертвой тишине послышался слабый голос главнокомандующего. Полк рявкнул: «Здравья желаем, ваше го го го го ство!» И опять всё замерло. Сначала Кутузов стоял на одном месте, пока полк двигался; потом Кутузов рядом с белым генералом, пешком, сопутствуемый свитою, стал ходить по рядам.
По тому, как полковой командир салютовал главнокомандующему, впиваясь в него глазами, вытягиваясь и подбираясь, как наклоненный вперед ходил за генералами по рядам, едва удерживая подрагивающее движение, как подскакивал при каждом слове и движении главнокомандующего, – видно было, что он исполнял свои обязанности подчиненного еще с большим наслаждением, чем обязанности начальника. Полк, благодаря строгости и старательности полкового командира, был в прекрасном состоянии сравнительно с другими, приходившими в то же время к Браунау. Отсталых и больных было только 217 человек. И всё было исправно, кроме обуви.
