Что такое POD и как его использовать. ШпаргалкаPerl, Python — блог программиста

Шпаргалка нужна не для изучения предмета, а для быстрой подсказки или использования в стиле "copy/paste". :) Так что, упреки в нераскрытости темы не принимаются. :)

Общее описание
Директивы POD
Основные элементы форматирования POD-документации
Стандартные блоки, включаемые в POD-документацию
- Типичное содержимое POD-документации для описания модуля
- Типичное содержимое POD-документации для описания приложения
Как читать POD-документацию
- Как читать
- Русскоязычная POD-документация
Примеры кода
- POD-документация добавлена в конец файла
- POD-документация встроена в код

Общее описание

POD можно встраивать в файлы любого типа. Можно создавать файлы, которые целиком состоят из
pod-документации.

POD-строками считаются все строки, начинающиеся со знака "=" в начале строки (без пробельных
отступов) и по строку "=cut" в начале строки (без пробельных отступов). Такие блоки пропускаются
интерпретатором, что позволяет внедрять эту документацию в любое место кода в любом количестве.

Директивы POD

Список директив POD

=head1 heading
=head2 heading
=over N
=item text
=back
=cut
=pod
=for X
=begin X
=end X

=head1 heading

=head2 heading

=over N

=item text

=back

=cut

=pod

=for X

=begin X

=end X

=headN heading

Создание заголовков заданного уровня. Остальной текст параграфа будет рассматриваться как описание заголовка.

Аналогичны заголовкам разделов и подразделов <h1>...</h1> и <h2>...</h2> в HTML.

=over N, =item text, =back

Элементы для создания списков. N - в элементе =over означает отступ (число в пробелах) списка от края документа.

Нумерованый список:

= over 4
= item 1.
AAAAAAA
= item 2.
BBBBBBB
= back

= over 4

= item 1.

AAAAAAA

= item 2.

BBBBBBB

= back

Маркированый список:

= over 4
=item *
text
=item *
...
= back

= over 4

=item *

text

=item *

...

= back

Именованый список:

= over
= item lancome ()
perfum
= item loreal ()
cosmetics
= back

= over

= item lancome ()

perfum

= item loreal ()

cosmetics

= back

=cut

Директива =cut указывает на конец любого блока pod-документации.

=pod

Начинает новый блок pod-документации.

=for X

Директивы =for, =begin и =end позволяют включать особые разделы, которые должны передаваться
в неизменном виде, но лишь определенным трансляторам. Трансляторы, которые узнают в TRANSLATOR
свое имя или псевдоним, обращают внимание на эти директивы; другие их полностью игнорируют.

Директива =for указывает, что оставшаяся часть этого абзаца предназначена конкретному транслятору.

=for html
<p>This is <b>HTML</b> paragraph</p>

1 2	=for html <p>This is <b>HTML</b> paragraph</p>

=begin X, =end X

Парные директивы =begin и =end действуют аналогично =for, но вместо того, чтобы принимать
только один абзац, они рассматривают весь текст между соответствующими =begin и =end как
предназначенный для конкретного транслятора.

Основные элементы форматирования POD-документации

I<text> - курсив
B<text> - жирный шрифт
C<text> - моноширинный шрифт, например Courier
S<text> - текст с неразрывными пробелами. Может окружать другие
последовательности.
L<name> - перекрестная ссылка на страницу руководства.
L<name/ident> - перекрестная ссылка на элемент страницы руководства.
L<text|name>

L<text|name/ident>- тоже, что и выше, но вместо ссылки будет
выводиться text (аналогично ссылкам в HTML).

F<pathname> - имя файла
E<escape> - вывод спецсимвола
E<lt>
E<gt>
E<sol> - литерал "/". Используется в ссылках L.
E<verbal> - литерал "|". Используется в ссылках L.
Z<> - символ нулевой ширины.

I<text> - курсив

B<text> - жирный шрифт

C<text> - моноширинный шрифт, например Courier

S<text> - текст с неразрывными пробелами. Может окружать другие

последовательности.

L<name> - перекрестная ссылка на страницу руководства.

L<name/ident> - перекрестная ссылка на элемент страницы руководства.

L<text|name>

L<text|name/ident>- тоже, что и выше, но вместо ссылки будет

выводиться text (аналогично ссылкам в HTML).

F<pathname> - имя файла

E<escape> - вывод спецсимвола

E<lt>

E<gt>

E<sol> - литерал "/". Используется в ссылках L.

E<verbal> - литерал "|". Используется в ссылках L.

Z<> - символ нулевой ширины.

Стандартные блоки, включаемые в POD-документацию

=head1 NAME Имя программы или модуля.

=head1 SYNOPSIS Одна строка, описывающая, что делает Ваша программа. Можно указать синтаксис вызова процедур модуля.

=head1 DESCRIPTION Документация.

=head1 SUBROUTINES/METHODS Описание подпрограмм и методов модуля.

=head1 BUGS Что сделано неправильно, почему и будет ли исправлено в следующих версиях программы.

=head1 TODO - Что еще следует сделать.

=head1 SEE ALSO Где можно найти дополнительную информацию по модулю, по теме.

=head1 AUTHOR - Автор.

=head1 USAGE - Использование.

=head1 REQUIRED ARGUMENTS - Необходимые аргументы.

=head1 OPTIONS - Опции.

=head1 DIAGNOSTICS Выполненные диагностики и проверки, тестирование.

=head1 CONFIGURATION AND ENVIRONMENT - Конфигурация и окружение.

=head1 DEPENDENCIES - Зависимости.

=head1 INCOMPATIBILITIES - Несовместимости.

=head1 HISTORY История изменений в порядке увеличения версии.

=head1 DISCLAIMER Правовая информация. Ответственность сторон.

=head1 BUGS AND LIMITATIONS - Что сделано неправильно, почему и будет ли
исправлено в следующих версиях программы. Ограничения использования.

=head1 EXAMPLES - Примеры использования.

=head1 FREQUENTLY ASKED QUESTIONS - Часто задаваемые вопросы.

=head1 COMMON USAGE MISTAKES - Часто встречающиеся ошибки использования.

=head1 THANKS Благодарности.

=head1 COPYRIGHT

Типичное содержимое POD-документации для описания модуля

=head1 NAME 
=head1 SYNOPSIS 
=head1 SUBROUTINES/METHODS

=head1 NAME

=head1 SYNOPSIS

=head1 SUBROUTINES/METHODS

Дополнительные блоки, включаются по мере необходимости:

=head1 VERSION
=head1 DIAGNOSTICS
=head1 CONFIGURATION AND ENVIRONMENT
=head1 DEPENDENCIES
=head1 INCOMPATIBILITIES
=head1 HISTORY
=head1 BUGS AND LIMITATIONS
=head1 EXAMPLES
=head1 FREQUENTLY ASKED QUESTIONS
=head1 COMMON USAGE MISTAKES
=head1 TODO
=head1 AUTHOR
=head1 SEE ALSO

=head1 VERSION

=head1 DIAGNOSTICS

=head1 CONFIGURATION AND ENVIRONMENT

=head1 DEPENDENCIES

=head1 INCOMPATIBILITIES

=head1 HISTORY

=head1 BUGS AND LIMITATIONS

=head1 EXAMPLES

=head1 FREQUENTLY ASKED QUESTIONS

=head1 COMMON USAGE MISTAKES

=head1 TODO

=head1 AUTHOR

=head1 SEE ALSO

Типичное содержимое POD-документации для описания приложения

=head1 NAME
=head1 USAGE
=head1 REQUIRED ARGUMENTS
=head1 OPTIONS
=head1 DESCRIPTION

=head1 NAME

=head1 USAGE

=head1 REQUIRED ARGUMENTS

=head1 OPTIONS

=head1 DESCRIPTION

При необходимости добавляются:

=head1 VERSION
=head1 DIAGNOSTICS
=head1 CONFIGURATION AND ENVIRONMENT
=head1 DEPENDENCIES
=head1 INCOMPATIBILITIES
=head1 BUGS AND LIMITATIONS
=head1 EXAMPLES
=head1 FREQUENTLY ASKED QUESTIONS
=head1 COMMON USAGE MISTAKES
=head1 LICENCE AND COPYRIGHT
=head1 TODO
=head1 AUTHOR
=head1 SEE ALSO

=head1 VERSION

=head1 DIAGNOSTICS

=head1 CONFIGURATION AND ENVIRONMENT

=head1 DEPENDENCIES

=head1 INCOMPATIBILITIES

=head1 BUGS AND LIMITATIONS

=head1 EXAMPLES

=head1 FREQUENTLY ASKED QUESTIONS

=head1 COMMON USAGE MISTAKES

=head1 LICENCE AND COPYRIGHT

=head1 TODO

=head1 AUTHOR

=head1 SEE ALSO

Как читать POD-документацию

Как читать

Прочитать встроенную в программу POD-документацию в отформатированном виде можно с помощью
поставляемой утилиты просмотра:

% perldoc program_with_pod

1	% perldoc program_with_pod

% perldoc perlpod

1	% perldoc perlpod

Кроме того, POD-документацию очень удобно читать при просмотре исходного кода модуля.

Описание в формате POD можно преобразовать в web-страницу поставляемой в комплекте с perl утилитой:

% pod2html --outfile=program.html program_with_pod

1	% pod2html --outfile=program.html program_with_pod

Для преобразования документации в обычный текстовый формат, можно использовать:

pod2text filename.pm > filename.txt

1	pod2text filename.pm > filename.txt

Русскоязычная POD-документация

Если русскоязычные символы в документации отражаются неадекватно, можно изменить настройки переменных окружения. А точнее - указать, какую кодировку использовать при чтении-редактировании файлов.

Просматриваем, что у нас уже имеется:

%env
USER=aninatalie
LOGNAME=aninatalie
HOME=/srvs/aninatalie
...
EDITOR=vi
PAGER=more

%env

USER=aninatalie

LOGNAME=aninatalie

HOME=/srvs/aninatalie

...

EDITOR=vi

PAGER=more

Добавляем новую переменную:

%setenv LC_CTYPE ru_RU.KOI8-R

1	%setenv LC_CTYPE ru_RU.KOI8-R

Смотрим результат:

%env
USER=aninatalie
LOGNAME=aninatalie
HOME=/srvs/aninatalie
...
PAGER=more
LC_CTYPE=ru_RU.KOI8-R

%env

USER=aninatalie

LOGNAME=aninatalie

HOME=/srvs/aninatalie

...

PAGER=more

LC_CTYPE=ru_RU.KOI8-R

Примеры кода

POD-документация добавлена в конец файла

Программный код:

#!/usr/local/bin/perl

hello();

sub hello {
        print "Hello, world!\n";
}

__END__

=head1 NAME

hello.pl - print string "Hello, world!"

=head1 SYNOPSIS

C<perl hello.pl>

=head1 DESCRIPTION

...some description...

=head1 AUTHOR

Aninatalie. aninatalie@my-mail.ru

#!/usr/local/bin/perl

hello();

sub hello {

print "Hello, world!\n";

}

__END__

=head1 NAME

hello.pl - print string "Hello, world!"

=head1 SYNOPSIS

C<perl hello.pl>

=head1 DESCRIPTION

...some description...

=head1 AUTHOR

Aninatalie. aninatalie@my-mail.ru

Вывод данной документации можно осуществить с помощью команды:

%perldoc hello.pl

1	%perldoc hello.pl

Вывод (что получилось, после выполнения данной команды):

%perldoc hello.pl
HELLO(1)              User Contributed Perl Documentation             HELLO(1)



NAME
       hello.pl - print string "Hello, world!"

SYNOPSIS
       perl hello.pl

DESCRIPTION
       ...some description...

AUTHOR
       Aninatalie. aninatalie@my-mail.ru

3rd Berkeley Distribution    perl 5.005, patch 03                     HELLO(1)
%

%perldoc hello.pl

HELLO(1) User Contributed Perl Documentation HELLO(1)

NAME

hello.pl - print string "Hello, world!"

SYNOPSIS

perl hello.pl

DESCRIPTION

...some description...

AUTHOR

Aninatalie. aninatalie@my-mail.ru

3rd Berkeley Distribution perl 5.005, patch 03 HELLO(1)

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

Программный код:

#!/usr/local/bin/perl

=head1 NAME

hello.pl - print string "Hello, world!"

=head1 SYNOPSIS

C<perl hello.pl>

=cut

hello();
by();

=head1 DESCRIPTION

...some description...

=item hello()

=cut

sub hello {
        print "Hello, world!\n";
}

=item by()

=cut

sub by {
        print "By!\n";
}

=head1 AUTHOR

Aninatalie. aninatalie@my-mail.ru

=cut

#!/usr/local/bin/perl

=head1 NAME

hello.pl - print string "Hello, world!"

=head1 SYNOPSIS

C<perl hello.pl>

=cut

hello();

by();

=head1 DESCRIPTION

...some description...

=item hello()

=cut

sub hello {

print "Hello, world!\n";

}

=item by()

=cut

sub by {

print "By!\n";

}

=head1 AUTHOR

Aninatalie. aninatalie@my-mail.ru

=cut

Вывод perldoc:

HELLO(1)              User Contributed Perl Documentation             HELLO(1)

NAME
       hello.pl - print string "Hello, world!"

SYNOPSIS
       perl hello.pl

DESCRIPTION
       ...some description...

       hello()

       by()

AUTHOR
       Aninatalie. aninatalie@my-mail.ru

HELLO(1) User Contributed Perl Documentation HELLO(1)

NAME

hello.pl - print string "Hello, world!"

SYNOPSIS

perl hello.pl

DESCRIPTION

...some description...

hello()

by()

AUTHOR

Aninatalie. aninatalie@my-mail.ru

Что такое POD и как его использовать. Шпаргалка: 2 комментария

Николай 22.01.2015 в 10:44 дп

отличная статья, спасибо
Валерий 13.12.2016 в 7:10 пп

Подскажите что что означает begin и в каком контексте лучше употреблять?
https://preply.com/question/chto-oznachaet-begin . Пора учить языки начинать

Комментарии запрещены.