perlpod

СОДЕРЖАНИЕ

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

НАЗВАНИЕ

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

ОПИСАНИЕ

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

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

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

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

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

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

Абзац verbatim

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

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

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

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

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

=pod
=head1 Heading Text
=head2 Heading Text
=head3 Heading Text
=head4 Heading Text
=head5 Heading Text
=head6 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

=head5 Heading Text

=head6 Heading Text

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

=head2 Object Attributes

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

=head2 Possible Values for C<$/>

Эти команды объяснены в разделе "Форматирующие коды" ниже.

Обратите внимание, что head5 и head6 были введены в 2020 году и в Pod::Simple 3.41, выпущенном в октябре 2020 года, поэтому они могут не поддерживаться используемым вами анализатором Pod.

=over indentlevel

=item stuff...

=back

Команды item, over и back требуют немного большего объяснения: "=over" начинает область, специально предназначенную для генерации списка с помощью команд "=item" или для отступа (групп) обычных абзацев. В конце вашего списка используйте "=back", чтобы завершить его. Опция indentlevel для "=over" указывает, насколько далеко нужно отступать, обычно в единицах em (где один em — это ширина символа "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" и т. д., — то есть такие, которые не похожи на маркеры или номера. (Если у вас есть список, который содержит и то, и другое: 1) элементы, которые не похожи на маркеры и номера, и 2) элементы, которые похожи, вы должны предварять элементы, похожие на маркеры или номера, с Z<>. Смотрите Z<> ниже для примера.)

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

=cut

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

=pod

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

=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> — эскейп-последовательность символа

Очень похоже на 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<...>").

Другое применение — указать, что данные в =item Z<>stuff... не должны рассматриваться как пуля или номер. Например, без Z<>, строка

=item Z<>500 Server error

может быть интерпретирована как пункт в пронумерованном списке, когда это не предназначено.

Ещё одно применение — сохранить визуальное пространство между =item строками. Если вы укажете

=item foo

=item bar

это обычно отобразится как

foo
bar

Возможно, это именно то, что вы хотите, но если вам нужно

foo

bar

можно использовать Z<> для достижения этого

=item foo

Z<>

=item bar

В большинстве случаев вам потребуется только одна пара угловых скобок для разграничения начала и конца кодов форматирования. Однако иногда вы захотите поместить реальную правую угловую скобку (знак больше, '>') внутри кода форматирования. Это особенно часто встречается при использовании кода форматирования для предоставления другого типа шрифта для фрагмента кода. Как и во всех вещах в 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 {
  ...

• Некоторые более старые трансляторы требуют, чтобы абзацы (включая абзацы команд, например, "=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.

АВТОР

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