Документация POD в Perl

В Perl документы POD (Plain Old Documentation) можно встраивать в модули или скрипты.

POD — это простой и удобный в использовании язык разметки.

Правила использования POD-документов:

Документы POD начинаются с=head1начало,=cutконец,=head1перед и после=cutдобавьте пустую строку.

Perl игнорирует документацию в POD. Далее следует пример:

Пример

#!/usr/bin/perl print "Hello, World\n"; =head1Пример Hello, World Это простой пример на Perl.=cut print "Hello, Example\n";

Выполнение вышеуказанной программы дает следующий вывод:

Hello, World
Hello, Example

Мы также можем использовать "__END__" или "__DATA__", чтобы "закомментировать" всё содержимое после строки, где они появляются:

Пример

#!/usr/bin/perl print "Hello, World\n"; while(<DATA>){ print $_; } __END__ =head1Пример Hello, World Это простой пример на Perl. print "Hello, Example\n";

Выполнение вышеуказанной программы дает следующий вывод:

Hello, World

=head1 Hello, World 实例
这是一个 Perl 的简单实例。
print "Hello, Example\n";

Следующий пример не читает документацию POD:

Пример

#!/usr/bin/perl print "Hello, World\n"; __END__ =head1Пример Hello, World Это простой пример на Perl. print "Hello, Example\n";

Выполнение вышеуказанной программы дает следующий вывод:

Hello, World

Что такое POD?

Pod (Plain Old Documentation) — это простой и удобный язык разметки, часто используемый для написания документации в программах и модулях Perl.

Конвертеры Pod могут преобразовывать Pod во многие форматы, такие как text, html, man и многие другие.

Язык разметки Pod содержит три основных типа: обычный, дословный и командный.

Обычный абзац: В обычных абзацах можно использовать коды форматирования, такие как жирный, курсив, стиль кода, подчеркивание и т. д.
Дословный абзац: Дословные абзацы используются для блоков кода или других частей, которые не нуждаются в обработке конвертером и не требуют переформатирования абзаца.
Командный абзац: Командные абзацы влияют на весь документ, обычно используются для настройки заголовков или маркеров списков.
Все командные абзацы (они занимают только одну строку) начинаются с "=", за которым следует идентификатор. Следующий текст будет затронут этой командой. К широко используемым командам теперь относятся
```
=pod (开始文档)
=head1 标题文本
=head2 标题文本
=head3 标题文本
=head4 标题文本
=over 缩进空格数量
=item 前缀
=back (结束列表)
=begin 文档格式
=end 结束文档格式
=for 格式文本
=encoding 编码类型
=cut (文档结束)
```

В Perl можно использовать pod2html **.pod >**.html для создания документов POD в формате HTML.

Рассмотрим следующий пример POD:

Пример

=beginhtml =encoding utf-8 =head1 Rookie Tutorial=cut

pod2html скопирует этот код дословно.

Используйте команду pod2html, чтобы выполнить и преобразовать его в HTML-код:

$ pod2html test.pod > test.html

Откройте test.html в браузере, раздел ссылок — это индекс, отображается следующим образом:

В следующем примере HTML записывается непосредственно в документ POD:

=begin html
=encoding utf-8

<h1>Example</h1>
<p> www.example.com </p>

=end html

pod2html скопирует этот код дословно.

Используйте команду pod2html, чтобы выполнить и преобразовать его в HTML-код:

$ pod2html test.pod > test.html

Откройте test.html в браузере, раздел ссылок — это индекс, отображается следующим образом:

Другие расширения