perlpod

СОДЕРЖАНИЕ

• НАЗВАНИЕ
• ОПИСАНИЕ
  • Обычный абзац
  • Абзац с буквальным воспроизведением текста
  • Абзац команды
  • Коды форматирования
  • Намерение
  • Встраивание POD в модули Perl
  • Рекомендации по написанию Pod
• СМОТРИТЕ ТАКЖЕ
• АВТОР

НАЗВАНИЕ

perlpod - формат документации Plain Old Documentation

ОПИСАНИЕ

Pod — это простой язык разметки, используемый для написания документации для Perl, программ Perl и модулей Perl.

Доступны переводчики для преобразования Pod в различные форматы, такие как обычный текст, HTML, страницы справки и многое другое.

Разметка Pod состоит из трех основных типов абзацев: обычный, буквальный и команды.

Обычный абзац

Большинство абзацев в вашей документации будут обычными блоками текста, как этот. Вы можете просто ввести свой текст без какой-либо разметки, а только с пустой строкой перед и после. При форматировании он будет подвергаться минимальному форматированию, например, будет переформатирован, вероятно, будет набран шрифтом с пропорциональным кеглем, и, возможно, даже выровнен по ширине.

Вы можете использовать коды форматирования в обычных абзацах, для жирного, курсива, code-style, гиперссылок и многого другого. Такие коды объяснены в разделе "Коды форматирования" ниже.

Абзац с буквальным воспроизведением текста

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

Абзац с буквальным воспроизведением текста отличается тем, что его первый символ — пробел или табуляция. (И обычно все его строки начинаются с пробелов и/или табуляций.) Он должен быть воспроизведен точно, при этом табуляции предполагаются на границах 8-го столбца. Нет специальных кодов форматирования, поэтому вы не можете сделать что-либо курсивным и т. п. \ означает \, и ничего больше.

Абзац команды

Абзац команды используется для специальной обработки целых фрагментов текста, обычно в виде заголовков или частей списков.

Все абзацы команд (которые, как правило, имеют только одну строку) начинаются с «=», за которым следует идентификатор, за которым следует произвольный текст, который команда может использовать по своему усмотрению. В настоящее время распознаются следующие команды:

=pod
=head1 Heading Text
=head2 Heading Text
=head3 Heading Text
=head4 Heading Text
=over indentlevel
=item stuff
=back
=begin format
=end format
=for format text...
=encoding type
=cut

Чтобы объяснить их по отдельности:

=head1 Heading Text

=head2 Heading Text

=head3 Heading Text

=head4 Heading Text

Head1-head4 создают заголовки, при этом head1 — это заголовок наивысшего уровня. Текст в остальной части этого абзаца — содержимое заголовка. Например:

=head2 Object Attributes

Текст «Атрибуты объекта» составляет заголовок. Текст в этих командах заголовка может использовать коды форматирования, как показано здесь:

=head2 Possible Values for C<$/>

Эти команды объяснены в разделе "Коды форматирования" ниже.

=over indentlevel

=item stuff...

=back

Команды «=over», «=item» и «=back» требуют немного больше пояснений: «=over» запускает область, специально предназначенную для создания списка с использованием команд «=item» или для отступа (групп) обычных абзацев. В конце вашего списка используйте «=back», чтобы завершить его. Параметр indentlevel в «=over» указывает, насколько далеко нужно отступать, обычно в емах (где один ем равен ширине «M» в базовом шрифте документа) или приблизительно эквивалентных единицах; если параметр indentlevel отсутствует, он по умолчанию равен четырём. (И некоторые форматеры могут просто проигнорировать значение indentlevel, которое вы укажете.) В stuff в =item stuff... вы можете использовать коды форматирования, как показано здесь:

=item Using C<$|> to Control Buffering

Эти команды объяснены в разделе "Коды форматирования" ниже.

Обратите также внимание на некоторые основные правила использования областей «=over» ... «=back»:

• Не используйте «=item» вне области «=over» ... «=back».

• Первым элементом после команды «=over» должен быть «=item», если только в данной области «=over» ... «=back» не будет никаких элементов.

• Не помещайте команды «=headn» в область «=over» ... «=back».

• И, пожалуй, самое важное, сохраняйте элементы согласованными: либо используйте «=item *» для всех элементов, чтобы создать маркеры; или используйте «=item 1.», «=item 2.» и т. д., чтобы создать нумерованный список; или используйте «=item foo», «=item bar» и т. д. — то есть вещи, которые не похожи на маркеры или номера.

  Если вы начинаете с маркеров или номеров, придерживайтесь их, поскольку форматеры используют тип первого «=item», чтобы определить способ форматирования списка.

=cut

Чтобы завершить блок Pod, используйте пустую строку, затем строку, начинающуюся с «=cut», и пустую строку после неё. Это позволяет Perl (и форматеру Pod) узнать, где возобновляется код Perl. (Пустая строка перед «=cut» технически не является необходимой, но многие старые процессоры Pod требуют её.)

=pod

Команда «=pod» сама по себе не делает ничего особенного, но она сигнализирует Perl (и форматерам Pod) о том, что здесь начинается блок Pod. Блок Pod начинается с любой команды абзаца, поэтому команда «=pod» обычно используется только тогда, когда вы хотите начать блок Pod с обычного абзаца или абзаца с буквальным воспроизведением текста. Например:

=item stuff()

This function does stuff.

=cut

sub stuff {
  ...
}

=pod

Remember to check its return value, as in:

  stuff() || die "Couldn't do stuff!";

=cut

=begin formatname

=end formatname

=for formatname text...

Команды «for», «begin» и «end» позволят вам иметь области текста/кода/данных, которые обычно не интерпретируются как обычный текст Pod, но передаются непосредственно определённым форматерам или являются иначе специальными. Форматер, который может использовать этот формат, будет использовать область, в противном случае она будет полностью проигнорирована.

Команда «=begin formatname», несколько абзацев и команда «=end formatname» означают, что текст/данные между ними предназначены для форматеров, которые понимают специальный формат под названием formatname. Например:

=begin html

<hr> <img src="thang.png">
<p> This is a raw HTML paragraph </p>

=end html

Команда «=for formatname text...» указывает, что оставшаяся часть только этого абзаца (начиная сразу после formatname) находится в этом специальном формате.

=for html <hr> <img src="thang.png">
<p> This is a raw HTML paragraph </p>

Это означает то же самое, что и область «=begin html» ... «=end html» выше.

То есть, с помощью «=for» вы можете иметь только один абзац текста (т. е. текст в «=foo targetname text...»), но с «=begin targetname» ... «=end targetname» вы можете иметь любое количество элементов между ними. (Обратите внимание, что по-прежнему должна быть пустая строка после команды «=begin» и пустая строка перед командой «=end».)

Вот несколько примеров использования этих команд:

=begin html

<br>Figure 1.<br><IMG SRC="figure1.png"><br>

=end html

=begin text

  ---------------
  |  foo        |
  |        bar  |
  ---------------

^^^^ Figure 1. ^^^^

=end text

Некоторые имена форматов, которые в настоящее время поддерживаются форматерами, включают «roff», «man», «latex», «tex», «text» и «html». (Некоторые форматеры будут рассматривать некоторые из них как синонимы.)

Имя формата «comment» часто используется для записи заметок (предположительно для себя), которые не появятся в любом отформатированном варианте документа Pod:

=for comment
Make sure that all the available options are documented!

Некоторые formatnames потребуют ведущего двоеточия (как в "=for :formatname" или "=begin :formatname" ... "=end :formatname"), чтобы указать, что текст не является сырыми данными, а является текстом Pod (возможно, содержащим коды форматирования), который просто не предназначен для обычного форматирования (например, может не быть обычным абзацем, но может использоваться для форматирования в качестве сноски).

=encoding encodingname

Эта команда используется для объявления кодировки документа. Большинству пользователей это не нужно; но если ваша кодировка не US-ASCII, поместите команду =encoding encodingname в самом начале документа, чтобы форматеры Pod знали, как декодировать документ. Для encodingname используйте имя, распознаваемое модулем Encode::Supported. Некоторые форматеры Pod могут попытаться угадать между кодировкой Latin-1 или CP-1252 по сравнению с UTF-8, но они могут ошибиться. Лучше быть явным, если вы используете что-либо, кроме строгого ASCII. Примеры:

=encoding latin1

=encoding utf8

=encoding koi8-r

=encoding ShiftJIS

=encoding big5

=encoding влияет на весь документ и должна встречаться только один раз.

И не забудьте, что все команды, кроме =encoding, действуют до конца своего абзаца, а не своей строки. Таким образом, в примерах ниже вы можете увидеть, что каждая команда требует пустой строки после неё, чтобы завершить свой абзац. (И некоторые старые переводчики Pod могут потребовать, чтобы строка =encoding имела пустую строку после неё, даже если она должна быть допустимой для пропуска.)

Вот несколько примеров списков:

=over

=item *

First item

=item *

Second item

=back

=over

=item Foo()

Description of Foo function

=item Bar()

Description of Bar function

=back

Коды форматирования

В обычных абзацах и в некоторых абзацах команд можно использовать различные коды форматирования (также известные как «внутренние последовательности»):

I<text> — текст курсивом

Используется для выделения ("be I<careful!>") и параметров ("redo I<LABEL>")

B<text> — жирный текст

Используется для переключателей ("perl's B<-n> switch"), программ ("some systems provide a B<chfn> for that"), выделения ("be B<careful!>") и так далее ("and that feature is known as B<autovivification>").

C<code> — текст кода

Отображает код в шрифте "печатной машинки" или указывает, что это программный текст ("C<gmtime($^T)>") или какой-либо другой вид компьютерного текста ("C<drwxr-xr-x>").

L<name> — гиперссылка

Существуют различные синтаксисы, перечисленные ниже. В приведенных синтаксисах text, name и section не могут содержать символы '/' и '|'; а любые '<' и '>' должны быть парными.

• L<name>

  Ссылка на страницу руководства по Perl (например, L<Net::Ping>). Обратите внимание, что name не должно содержать пробелов. Этот синтаксис также иногда используется для ссылок на страницы руководства Unix, как в L<crontab(5)>.

• L<name/"sec"> или L<name/sec>

  Ссылка на раздел в другой странице руководства. Например, L<perlsyn/"For Loops">

• L</"sec"> или L</sec>

  Ссылка на раздел в данной странице руководства. Например, L</"Object Methods">

Раздел начинается с именованного заголовка или элемента. Например, L<perlvar/$.> или L<perlvar/"$."> оба ссылаются на раздел, начинающийся с "=item $." в perlvar. А L<perlsyn/For Loops> или L<perlsyn/"For Loops"> оба ссылаются на раздел, начинающийся с "=head2 For Loops" в perlsyn.

Для управления текстом, используемым для отображения, используется "L<text|...>", например:

• L<text|name>

  Ссылка на этот текст на той странице руководства. Например, L<Perl Error Messages|perldiag>

• L<text|name/"sec"> или L<text|name/sec>

  Ссылка на этот раздел на этой странице руководства. Например, L<postfix "if"|perlsyn/"Statement Modifiers">

• L<text|/"sec"> или L<text|/sec> или L<text|"sec">

  Ссылка на этот раздел в данной странице руководства. Например, L<the various attributes|/"Member Data">

Или вы можете ссылаться на веб-страницу:

• L<scheme:...>

  L<text|scheme:...>

  Ссылки на абсолютный URL. Например, L<http://www.perl.org/> или L<The Perl Home Page|http://www.perl.org/>.

E<escape> — escape-последовательность символа

Очень похож на HTML/XML &foo; "ссылки на сущности":

• E<lt> — буквальный символ '<' (меньше)

• E<gt> — буквальный символ '>' (больше)

• E<verbar> — буквальный символ '|' (вертикальная черта)

• E<sol> — буквальный символ '/' (сольдус)

  Вышеперечисленные четыре необязательны, за исключением других кодов форматирования, особенно L<...>, и когда им предшествует заглавная буква.

• E<htmlname>

  Некоторые нечисловые имена сущностей HTML, такие как E<eacute>, означающие то же, что и é в HTML — то есть, маленькая буква «е» с острым (/-образным) акцентом.

• E<number>

  Символ ASCII/Latin-1/Unicode с этим номером. Ведущая "0x" означает, что число — шестнадцатеричное, как в E<0x201E>. Ведущая "0" означает, что число — восьмеричное, как в E<075>. В противном случае число интерпретируется как десятичное, как в E<181>.

  Обратите внимание, что более старые форматировщики Pod могут не распознавать восьмеричные или шестнадцатеричные числовые escape-последовательности, а многие форматировщики не могут надёжно отображать символы выше 255. (Некоторые форматировщики могут даже использовать урезанные рендеринги символов Latin-1/CP-1252, например, отобразить E<eacute> просто как обычное "e").

F<filename> — используется для имён файлов

Обычно отображается курсивом. Пример: "F<.cshrc>"

S<text> — текст содержит неразрывные пробелы

Это означает, что слова в тексте не должны быть разбиты на строки. Пример: S<$x ? $y : $z>.

X<topic name> — запись в индексе

Это игнорируется большинством форматировщиков, но некоторые могут использовать его для построения индексов. Он всегда отображается как пустая строка. Пример: X<absolutizing relative URLs>

Z<> — нулевой (без эффекта) код форматирования

Это редко используется. Это один из способов обойти использование кода E<...> иногда. Например, вместо "NE<lt>3" (для "N<3") можно написать "NZ<><3" (символы "Z<>" разделяют "N" и "<," так что их нельзя рассматривать как часть (вымышленного) кода "N<...>").

Большую часть времени вам понадобится только одна пара угловых скобок для разграничения начала и конца кодов форматирования. Однако иногда вам захочется поместить реальную правую угловую скобку (знак больше, '>') внутри кода форматирования. Это особенно часто встречается при использовании кода форматирования для предоставления другого типа шрифта для фрагмента кода. Как и во всем в Perl, существует более одного способа сделать это. Один способ — просто экранировать закрывающую скобку с помощью E кода:

C<$a E<lt>=E<gt> $b>

Это даст: "$a <=> $b"

Более читабельный и, возможно, более "простой" способ — использовать альтернативный набор разделителей, не требующий экранирования одного символа '>'. Двойные угловые скобки ("<<" и ">>") можно использовать только в том случае, если сразу после открывающего разделителя и непосредственно перед закрывающим разделителем есть пробелы! Например, следующее сработает:

C<< $a <=> $b >>

На самом деле, вы можете использовать столько пар угловых скобок, сколько хотите, при условии, что у вас одинаковое количество скобок в открывающих и закрывающих разделителях, и убедитесь, что пробелы непосредственно следуют за последним '<' открывающего разделителя и непосредственно предшествуют первому '>' закрывающего разделителя. (Пробелы игнорируются.) Поэтому и следующее также сработает:

C<<< $a <=> $b >>>
C<<<<  $a <=> $b     >>>>

И все они означают ровно то же, что и это:

C<$a E<lt>=E<gt> $b>

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

C<< $a E<lt>=E<gt> $b >>

В качестве дополнительного примера, это означает, что если вы хотите поместить эти части кода в C (код) стиле:

open(X, ">>thing.dat") || die $!
$foo->bar();

вы можете сделать это так:

C<<< open(X, ">>thing.dat") || die $! >>>
C<< $foo->bar(); >>

что, предположительно, легче читать, чем старый способ:

C<open(X, "E<gt>E<gt>thing.dat") || die $!>
C<$foo-E<gt>bar();>

В настоящее время это поддерживается pod2text (Pod::Text), pod2man (Pod::Man) и любыми другими переводчиками pod2xxx или Pod::Xxxx, которые используют Pod::Parser 1.093 или новее, или Pod::Tree 1.02 или новее.

Намерение

Намерение — простота использования, а не выразительность. Абзацы выглядят как абзацы (формат блоков), чтобы они визуально выделялись, и чтобы я мог легко их переформатировать с помощью fmt (это F7 в моей версии vi или Esc Q в моей версии emacs). Я хотел, чтобы переводчик всегда оставлял ', ` и " кавычки в режиме verbatim, чтобы я мог прочитать работающую программу, сдвинуть её на четыре пробела и получить её вывод, ну, в прямом смысле. И, предположительно, в моноширинном шрифте.

Формат Pod не обязательно подходит для написания книги. Pod просто предназначен для создания надёчного общего источника для nroff, HTML, TeX и других языков разметки, используемых для онлайн-документации. Существуют переводчики для pod2text, pod2html, pod2man (это для nroff(1) и troff(1)), pod2latex и pod2fm. Различные другие доступны в CPAN.

Встраивание Pod в модули Perl

Вы можете встраивать документацию Pod в свои модули и скрипты Perl. Начните свою документацию с пустой строки, команды "=head1" в начале и завершите её командой "=cut" и пустой строкой. Интерпретатор perl проигнорирует текст Pod. Вы можете поместить утверждение Pod там, где perl ожидает начало нового утверждения, но не внутри утверждения, так как это приведёт к ошибке. Обратитесь к любым предоставленным модулям библиотеки для примеров.

Если вы собираетесь поместить свой Pod в конце файла, и вы используете метку __END__ или __DATA__ cut, убедитесь, что перед первой командой Pod там есть пустая строка.

__END__

=head1 NAME

Time::Local - efficiently compute time from local and GMT time

Без этой пустой строки перед "=head1" многие переводчики не распознали бы "=head1" как начало блока Pod.

Рекомендации по написанию Pod

• Команда podchecker предназначена для проверки синтаксиса Pod на ошибки и предупреждения. Например, она проверяет наличие совершенно пустых строк в блоках Pod и неизвестных команд и кодов форматирования. Вы по-прежнему должны также пропустить свой документ через один или несколько переводчиков и проверить результат, или распечатать результат и проверить его. Некоторые найденные проблемы могут быть ошибками в переводчиках, которые вы можете или не захотите обойти.

• Если вы более знакомы с написанием документации на HTML, чем на Pod, вы можете попробовать написать документацию на простом HTML и преобразовать её в Pod с помощью экспериментального модуля Pod::HTML2Pod (доступен в CPAN) и посмотреть на полученный код. Экспериментальный модуль Pod::PXML в CPAN также может быть полезен.

• Многие старые переводчики Pod требуют, чтобы строки перед каждой командой Pod и после каждой команды Pod (включая "=cut"!) были пустыми. Если у вас есть, по-видимому, пустая строка с пробелами, это может не считаться разделителем для этих переводчиков, и это может вызвать странное форматирование.

  Вместо этого сделайте так:

  # - - - - - - - - - - - -
  =item $firecracker->boom()
  
  This noisily detonates the firecracker object.
  =cut
  sub boom {
  ...

  ...приведёт к тому, что такие переводчики Pod вообще не увидят блок Pod.

  Вместо этого сделайте так:

  # - - - - - - - - - - - -
  
  =item $firecracker->boom()
  
  This noisily detonates the firecracker object.
  
  =cut
  
  sub boom {
  ...

• Некоторые старые переводчики Pod требуют, чтобы абзацы (включая абзацы команд, такие как "=head2 Functions") были разделены абсолютно пустыми строками. Если у вас есть, по-видимому, пустая строка с некоторыми пробелами, это может не считаться разделителем для этих переводчиков, что может привести к странному форматированию.

• Старые переводчики могут добавлять слова вокруг ссылки L<>, поэтому L<Foo::Bar> может стать "документацией manpage для Foo::Bar", например. Поэтому вы не должны писать вещи вроде the L<foo> documentation, если вы хотите, чтобы переведённый документ читался осмысленно. Вместо этого, напишите the L<Foo::Bar|Foo::Bar> documentation или L<the Foo::Bar documentation|Foo::Bar>, чтобы контролировать, как будет выглядеть ссылка.

• Переход за 70-й столбец в блоке verbatim может быть некрасиво обернут некоторыми форматировщиками.

См. также

perlpodspec, «PODs: Embedded Documentation» в perlsyn, perlnewmod, perldoc, pod2html, pod2man, podchecker.

АВТОР

Larry Wall, Sean M. Burke