perlpod

СОДЕРЖАНИЕ

• ИМЯ
• ОПИСАНИЕ
  • Обычный абзац
  • Абзац с verbatim-текстом
  • Абзац с командой
  • Коды форматирования
  • Назначение
  • Встраивание Pod в модули 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
=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

Команды item, over и 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» и т. д. — то есть вещи, которые совершенно не похожи на пули или числа. (Если у вас есть список, содержащий и то, и другое: 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<> — код форматирования «null» (без эффекта)

Это используется редко. Это один из способов обойти использование кода 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 {
  ...

• Некоторые старые переводчики 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: Embedded Documentation" в perlsyn, perlnewmod, perldoc, pod2html, pod2man, podchecker.

АВТОР

Larry Wall, Sean M. Burke