POD формат — Вікіпедія

POD формат (англ. Plain Old Documentation) — спрощена мова розмітки тексту, що використовується для документування Perl програм.

Особливості

[ред. | ред. код]

POD формат розроблявся як проста й водночас практична мова документування. Вона цілеспрямовано не включає механізми для опису шрифтів, зображень, кольорів або таблиць. Основні цілі формату:

  • простий для парсингу;
  • простий для перетворювання в інші формати: man[1], HTML[2], txt[3], XML, TeX або Markdown тощо;
  • легкість наведення зразків коду або їх частин;
  • легкість читання в початковому вигляді, без попереднього форматування;
  • легкість написання.

PseudoPOD — розширена версія POD формату, що підтримує таблиці та виноски, що називається PseudoPOD, та була розроблена й використана видавництвом O'Reilly & Associates для створення декількох Perl-книг, однією з яких є Programming Perl.

Pod дозволяє легко писати man-довідки для користувачів, на відміну від інших систем документування, таки як Docstring або Javadoc, які більш призначені для розробників й описують початковий код.

Використання

[ред. | ред. код]

POD застосовується для формування більшості документів в Perl-спільноті. Це опис як самого Perl, так й опис майже всіх модулів до нього, статті на Perl.com [Архівовано 30 червня 2005 у Wayback Machine.], а також опис віртуальної машини Parrot.

Хоча документація в POD форматі може бути доволі просто прочитана в своєму первинному вигляді, зазвичай її конвертують в більш читабельні формати засобами perldoc.

Файли в форматі POD мають розширення .pod Також фрагменти документації в POD форматі, можуть бути безпосередньо в Perl коді, файли якого зазвичай мають розширення .pl або .pm. Perl-інтерпретатор розпізнає POD-документацію в коді та ігнорує її.

Приклад

[ред. | ред. код]

Нижче приклад коректного за синтаксисом документу в POD форматі з дотриманням прийнятої структури організації в Perl суспільстві документів.[4]

=head1 NAME My::Module - назва модуля  =head1 SYNOPSIS     my $object = My::Module->new();     print $object->as_string;  =head1 DESCRIPTION     use My::Module;  Це неіснуючий модуль, він зроблений з метою продемонструвати POD формат.  =head2 Methods  =over 12  =item C<new>  =item C<as_string>   Повертає представлення об'єкта як строковому вигляді. В основному для налагодження.  =back  =head1 LICENSE   Модуль розповсюджується на умовах GPL ліцензії.  Див. <perlartistic>.  =head1 AUTHOR   Juerd - L<http://juerd.nl/>  =head1 SEE ALSO   L<perlpod>, L<perlpodspec>  =cut 

Див. також

[ред. | ред. код]

Примітки

[ред. | ред. код]
  1. pod2man довідка. Архів оригіналу за 17 липня 2018. Процитовано 5 серпня 2018.
  2. pod2html довідка
  3. pod2text довідка
  4. Juerd. Plain Old Documentation in 5 minutes. Архів оригіналу за 12 серпня 2017. Процитовано 2018.08.05.