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
=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" и т.д.—то есть вещи, которые ни на что не похожи на маркеры или номера. (Если у вас есть список, содержащий и то, что не похоже на маркеры или числа, и то, что похоже, вы должны предварять элементы, похожие на маркеры или числа, 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...

Для, начала и конца позволят вам иметь области текста/кода/данных, которые обычно не интерпретируются как обычный текст 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 сущности:

• 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 (код) стилем:

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 и других языков разметки, используемых для онлайн-документации. Для преобразования Pod в другие форматы существуют подпрограммы 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