Perl - встроенная документация

Вы можете встроить документацию Pod (Plain Old Text) в свои модули и сценарии Perl. Ниже приводится правило использования встроенной документации в вашем Perl-коде.

Начните свою документацию с пустой строки a =head1 в начале и завершите ее знаком =cut

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

#!/usr/bin/perl

print "Hello, World\n";

=head1 Hello, World Example
This example demonstrate very basic syntax of Perl.
=cut

print "Hello, Universe\n";

Когда приведенный выше код выполняется, он дает следующий результат -

Hello, World
Hello, Universe

Если вы собираетесь поместить свой Pod в конец файла и используете метку выреза __END__ или __DATA__, обязательно поместите пустую строку перед первой командой Pod, как показано ниже, в противном случае без пустой строки перед знак =head1, многие переводчики не узнали бы =head1 как начало блока Pod.

#!/usr/bin/perl

print "Hello, World\n";

while(<DATA>) {
  print $_;
}

__END__

=head1 Hello, World Example
This example demonstrate very basic syntax of Perl.
print "Hello, Universe\n";

Когда приведенный выше код выполняется, он дает следующий результат -

Hello, World

=head1 Hello, World Example
This example demonstrate very basic syntax of Perl.
print "Hello, Universe\n";

Давайте возьмем еще один пример для того же кода без чтения части DATA -

#!/usr/bin/perl

print "Hello, World\n";

__END__

=head1 Hello, World Example
This example demonstrate very basic syntax of Perl.
print "Hello, Universe\n";

Когда приведенный выше код выполняется, он дает следующий результат -

Hello, World

Что такое POD?

Pod - это простой в использовании язык разметки, используемый для написания документации для Perl, программ Perl и модулей Perl. Существуют различные переводчики для преобразования Pod в различные форматы, такие как обычный текст, HTML, страницы руководства и другие. Разметка пода состоит из трех основных типов абзацев:

Ordinary Paragraph - Вы можете использовать коды форматирования в обычных абзацах, для жирного шрифта, курсива, стиля кода, гиперссылок и т. Д.
Verbatim Paragraph - Дословные абзацы обычно используются для представления кодового блока или другого текста, который не требует специального синтаксического анализа или форматирования и который не следует переносить.
Command Paragraph- Командный абзац используется для специальной обработки целых фрагментов текста, обычно как заголовков или частей списков. Все абзацы команд начинаются со знака =, за которым следует идентификатор, за которым следует произвольный текст, который команда может использовать как угодно. В настоящее время распознанные команды:

=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

Примеры POD

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

=head1 SYNOPSIS
Copyright 2005 [TUTORIALSOPOINT].
=cut

Вы можете использовать pod2html доступная в Linux утилита для преобразования вышеуказанного POD в HTML, поэтому она даст следующий результат:

Затем рассмотрим следующий пример -

=head2 An Example List

=over 4
=item * This is a bulleted list.
=item * Here's another item.
=back
=begin html
<p>
Here's some embedded HTML.  In this block I can
include images, apply <span style="color: green">
styles</span>, or do anything else I can do with
HTML.  pod parsers that aren't outputting HTML will
completely ignore it.
</p>

=end html

Когда вы конвертируете указанный выше POD в HTML с помощью pod2html, он даст следующий результат:

An Example List
   This is a bulleted list.
   Here's another item.
Here's some embedded HTML. In this block I can include images, apply 
styles, or do anything else I can do with HTML. pod parsers that aren't 
outputting HTML will completely ignore it.