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
=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

Для =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 с обычного абзаца или абзаца фиксированного формата. Например:

=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!

Некоторые 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" с острым (/-образным) акцентом.

• E<number>

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

  Обратите внимание, что более старые форматировщики Pod могут не распознавать восьмеричные или шестнадцатеричные числовые экранирования, и что многие форматировщики не могут надежно отображать символы выше 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<> — код форматирования 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 (код) стиле:

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). Я хотел, чтобы переводчик всегда оставлял ' и ` и " кавычки в текстовом режиме, чтобы я мог проглотить работающую программу, сместить её на четыре пробела и напечатать, э-э, дословно. И, предположительно, шрифтом с фиксированной шириной.

Формат 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