Обычная старая документация

Plain Old Documentation ( pod ) — это легкий язык разметки, используемый для документирования языка программирования Perl, а также модулей и программ Perl.

Дизайн

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

• Легко разобрать
• Легко конвертировать в другие форматы, такие как XML , TeX или Markdown.
• Легко включить пример кода
• Легко читается без форматтера модулей (т. е. в виде исходного кода).
• Легко писать в

Расширенная версия модуля, поддерживающего таблицы и сноски, под названием PseudoPOD, использовалась O'Reilly & Associates для создания нескольких книг по Perl, в первую очередь «Программирование на Perl» Ларри Уолла , Тома Кристиансена и Джона Орванта .

Pod позволяет легко писать страницы руководства , которые хорошо подходят для документов, ориентированных на пользователя. Напротив, другие системы документации, такие как Docstring Java Python или Javadoc , хотя и могут использоваться для пользовательской документации, предназначены для облегчения создания ориентированной на разработчиков документации об исходном коде программного проекта.

Используйте

Pod — это язык, используемый для большей части документации в мире Perl. Сюда входит сам Perl, почти все общедоступные модули , множество скриптов , большая часть проектной документации, множество статей на Perl.com и других веб-сайтах, связанных с Perl. и виртуальная машина Parrot .

Pod редко читается в необработанном виде, хотя он предназначен для чтения без помощи инструментов форматирования. Вместо этого он читается с помощью инструмента perldoc или преобразуется в справочные страницы Unix или HTML-страницы веб-стандарта.

Также возможно использовать pod в других контекстах, кроме Perl. Например, добавить в bash-скрипты простую документацию , которую потом можно будет легко преобразовать в man-страницы. Такое использование основано на хаках, специфичных для языка, чтобы скрыть части модуля (частей), например (в bash) добавление к разделу POD префикса строки :<<=cut bash который работает, вызывая no-op : команда, со всем блоком Pod в качестве документа здесь в качестве входных данных.

Чистые файлы pod обычно имеют расширение .pod, но pod чаще всего используется непосредственно в Perl код, который обычно использует .pl и .pm расширения. (Перл интерпретатора синтаксический анализатор предназначен для игнорирования модуля pod в коде Perl.) В файлах исходного кода документация обычно располагается после __END__ маркер (который также помогает подсвечивать синтаксис в некоторых редакторах для отображения его в виде комментариев).

Pod можно легко преобразовать в другие форматы, например в некоторые из различных форматов Wiki , такие как: WikiWikiWeb , Kwiki , TWiki , UseModWiki , TiddlyWiki , Textile , MediaWiki , MoinMoin или Confluence, используя Pod::Simple::Wiki.

Пример

Этот документ представляет собой синтаксически правильный модуль, который также пытается следовать основным соглашениям по именованию разделов.

=head1 NAME

My::Module - An example module

=head1 SYNOPSIS

    use My::Module;
    my $object = My::Module->new();
    print $object->as_string;

=head1 DESCRIPTION

This module does not really exist, it
was made for the sole purpose of
demonstrating how POD works.

=head2 Methods

=over 12

=item C<new>

Returns a new My::Module object.

=item C<as_string>

Returns a stringified representation of
the object. This is mainly for debugging
purposes.

=back

=head1 LICENSE

This is released under the Artistic License. 
See L<perlartistic>.

=head1 AUTHOR

Juerd - L<http://juerd.nl/>

=head1 SEE ALSO

L<perlpod>, L<perlpodspec>

=cut

Подробности форматирования

Файлы Pod записываются в ASCII -совместимой кодировке , например Latin-1 или UTF-8 . Анализатор модуля всегда предполагает, что анализируемый им файл не начинается с pod; он игнорирует все строки пока он не увидит директиву модуля. Директивы pod должны располагаться в начале строки, и все они начинаются со знака равенства. Затем анализатор модуля будет считать, что все последующие строки являются модулями, пока не встретит строку, состоящую из директивы «=cut». Любой контент, следующий за ним, игнорируется до тех пор, пока анализатор не встретит другую директиву модуля. Таким образом, pod можно смешивать с исполняемым исходным кодом, если синтаксический анализатор языка умеет распознавать и игнорировать pod.

Содержимое модуля разделено на абзацы пустыми строками. Абзацы, начинающиеся с пробелов — табуляции или пробелов, считаются «дословными абзацами» и остаются полностью неформатированными; они используются для примеров кода, изображений ASCII и т. д. Параграфы, начинающиеся со знака равенства, являются «параграфами команд»; последовательность буквенно-цифровых символов, следующих сразу за знаком равенства, рассматривается как директива модуля, а остальная часть абзаца форматируется в соответствии с этой директивой. Некоторые директивы также влияют на следующие параграфы. Если абзац начинается с чего-то помимо знака равенства или пробела, он считается «обычным абзацем».

Как обычные абзацы, так и содержимое командных абзацев анализируются на предмет кодов форматирования. Форматирование в модуле очень простое; в основном он ограничен жирным, курсивом, подчеркнутым, моноширинным и некоторыми другими форматами. Существует также код для связи между документами модуля или с другим разделом одного и того же документа. Коды форматирования состоят из:

• Одна заглавная буква, за которой следует знак «меньше» (<), форматируемое содержимое и знак «больше» (>), например B<bolded text>, или
• Одна заглавная буква, два или более знаков «меньше» (<<), пробел, форматируемое содержимое, еще один пробел и такое же количество знаков «больше», которое использовалось ранее, например B<< bolded text >>. Эта форма часто используется для фрагментов кода, содержащих знак «больше», который в противном случае привел бы к завершению кода форматирования.

Команды в модуле включают четыре уровня заголовков, маркированные и нумерованные списки, а также команды для пометки разделов как на другом языке. Последняя функция позволяет задавать специальное форматирование синтаксическим анализаторам, которые ее поддерживают.

См. также

• Сравнение генераторов документации

Ссылки

• Уолл, Ларри; Кристиансен, Том; И Орвант, Джон (2000). Программирование на Perl (3-е изд.). Севастополь: О'Рейли и партнеры. ISBN   0-596-00027-8 .
• Глава 15, «Работа с Pod», в книге Брайана Д. Фой (2007). Владение Перлом . Севастополь: О'Рейли Медиа . ISBN   0-596-52724-1 .
• Раздел 5.2, «Встраивание документации в сценарии оболочки», Альбинг, Карл; Воссен, JP; и Кэмерон Ньюэм. (2007). Поваренная книга bash: решения и примеры для пользователей bash ; О'Рейли и партнеры. ISBN   0-596-52678-4 .

Внешние ссылки

• perlpod (документация на модуле для людей, пишущих в нем документы)
• perlpodspec (документация по поду для людей, пишущих для него парсеры)
• Страницы руководства Perl в формате raw pod
• (ПсевдоПОД)
• Каталог содержит множество модулей со встроенным форматированием подов.
• Модуль Getopt::Euclid автоматически анализирует вводимые данные в Perl-скрипт на основе тегов модуля.
• The Pod::Simple::Wiki конвертирует модуль в различные Wiki. форматы
• Pod ::Markdown конвертирует модуль в Markdown