perlpod

СОДЕРЖАНИЕ

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

НАЗВАНИЕ

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

ОПИСАНИЕ

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

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

Разметка 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", чтобы его завершить. Опция indentlevel для "=over" указывает, на сколько увеличить отступ, обычно в емах (где один ем — ширина «М» в базовом шрифте документа) или приблизительно эквивалентных единицах; если опция 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!

Некоторые форматные имена потребуют ведущего двоеточия (как в "=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> — управляющий символ

Очень похож на 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 могут не распознавать восьмеричные или шестнадцатеричные управляющие символы, а многие форматировщики не могут надёжно отображать символы с кодом выше 255. (Некоторые форматировщики могут даже использовать урезанные рендеринги символов Latin-1/CP-1252, например, отображать E<eacute> просто как обычное «е».)

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, чтобы я мог прочитать рабочую программу, сместить её на четыре пробела и напечатать её, ну, 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> может стать «страница справки Foo::Bar», например. Поэтому не нужно писать такие вещи, как the L<foo> documentation, если вы хотите, чтобы переведённый документ читался разумно. Вместо этого напишите the L<Foo::Bar|Foo::Bar> documentation или L<the Foo::Bar documentation|Foo::Bar>, чтобы контролировать, как отображается ссылка.

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

См. также

perlpodspec, "PODs: Встроенная документация" в perlsyn, perlnewmod, perldoc, pod2html, pod2man, podchecker.

АВТОР

Ларри Уолл, Шон М. Берк