Что такое POD и как его использовать. Шпаргалка

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


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

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

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

 


Директивы POD

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

=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 *
text
=item *
...
= back

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

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

 


=cut

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

 


=pod

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

 


=for X

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

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

=for html

This is <b>HTML</b> paragraph

 


=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<> - символ нулевой ширины.

 


Стандартные блоки, включаемые в 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 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 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

% perldoc perlpod

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

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

% pod2html --outfile=program.html program_with_pod

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

pod2text filename.pm > filename.txt

 


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

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

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

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

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

%setenv 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

=head1 DESCRIPTION

...some description...

=head1 AUTHOR

Aninatalie. [email protected]

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

%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. [email protected]

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

=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. [email protected]

=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. [email protected]

Поделись ссылкой с друзьями!

21 Ноя 2010 | Filed in Perl - документация |

В связи с большим количеством спама, все комментарии проходят предварительную модерацию. Извините, за предоставленные неудобства.

1 комментарий

Other Links to this Post

RSS-лента комментариев к этой записи.

Оставить комментарий

*