Если во время анализа исходного текста Perl обнаруживает строку, начинающуюся со знака = (там, где ожидается новая команда), он игнорирует весь текст до строки, начинающейся с =cut, после чего продолжает анализировать код. Это позволяет смешивать в программах или файлах модулей Perl код и документацию. Поскольку формат pod является сугубо текстовым, никакого особого форматирования не требуется. Трансляторы стараются проявить интеллект и преобразуют вывод так, чтобы программисту не приходилось особым образом форматировать имена переменных, вызовы функций и т. д.

Вместе с Perl поставляется несколько программ-трансляторов, которые фильтруют документацию в формате pod и преобразуют ее в другой формат вывода. Утилша pod2man преобразует pod в формат troff, используемый в программе man или в системах верстки и печати. Утилитаpod2html создает Web-страницы, работающие в системах, не принадлежащих к семейству UNIX. Утилита pod2text преобразует pod в простой ASCII-текст. Другие трансляторы (pod2ipf, pod2fm, pod2text, pod2latex и pod2ps) могут входить в поставку Perl или распространяются через CPAN

Многие книги пишутся в коммерческих текстовых редакторах с ограниченными сценарными возможностями... но только не эта! Она была написана в формате pod в простых текстовых редакторах (Том использовал ы, а Нат - emacs). На стадии технической правки книга была преобразована в формат troff специальным транслятором pod2ora, написанным Ларри. Окончательный вариант книги был получен преобразованием pod-файлов в формат FrameMaker.

Хотя Bperlpod(l) приведено общее описание pod, вероятно, .этот формат удобнее изучать на примере готовых модулей Если вы начали создавать собственные модули с помощью утилиты h2xs, то у вас уже имеются образцы. Утилита Makefile знает, как преобразовать их в формат man и установить страницы руководства так, чтобы их могли прочитать другие. Кроме того, программа perWoc может транслировать документацию pod с помощью pod2text.

Абзацы с отступами остаются без изменений. Другие абзацы переформатируются для размещения на странице. В pod используются лишь два вида служебной разметки: абзацы, начинающиеся со знака = и одного или нескольких слов, и внутренние последовательности в виде буквы, за которой следует текст в угловых скобках. Теги абзацев определяют заголовки, перечисляемые элементы списков и служебные символы, предназначенные для конкретного транслятора Последовательности в угловых скобках в основном используются для изменения начертания (например, выбора полужирного, курсивного или моьюширинного шрифта). Приведем пример директивы =head2 в сочетании с изменениями шрифта:

=head2 Discussion

If we had a dot-h file with function prototype declarations, we could include that, but since we re writing this one from scratch, we И use the -c flag to omit building code to translate any #define symbols The -n flag says to create a module directory named FineTime/, which will have the following files

12.7. Построение и установка модуля CPAN 441

Последовательность =for определяет код для выходных файлов конкретного формата. Например, в этой книге, главным образом написанной в формате pod, присутствуют вызовы стандартных средств troff: eqn, tbl и pic. Ниже показан пример внутреннего вызова eqn, который обрабатывается лишь трансляторами, производящими данные в формате troff:

=for troff EQ

log sub n (x) = { {log sub e (x)} over {log sub e (n)} } EN

Формат pod также позволяет создавать многострочные комментарии. В языке С комментарий /* */ может включать несколько строк текста - вам не придется ставить отдельный маркер в каждой строке. Поскольку Perl игнорирует директивы pod, этим можно воспользоваться для блочного комментирования. Весь фокус заключается в том, чтобы найти директиву, игнорируемую трансляторами pod. Например, можно воспользоваться тегом for later или for nobody:

=for later

next if 1 "$,

s/"( )/>$1/,

s/( {73}) VSKSNIPV,

=cut back to perl или парой =begin и =end: =begin comment

if (iopen(FILE, Sfile)) { unless ($opt q) {

warn $me $file $i\n , $Errors++,

next FILE,

$total = 0, $matches = 0,

=end comment

> Смотри также-

Раздел «POD: Enbedded Documentation* вperlsyn{l);perlpod(l),pod2man{i), pod2html{\) иpod2text(i).

12.7. Построение и установка модуля CPAN

Проблема

Требуется установить файл модуля, загруженный с CPAN или взятый с компакт-диска.

Этот формат отличается от формата zip, используемого на большинстве компьютеров с Windows, однако новые версии Winzip читают его. До выхода Perl 5.005 для построения модулей CPAN использовалась стандартная версия Perl для Win32, а не ActiveState. Также существуют бесплатные версии tar и GNU tar для систем Microsoft

Решение

Введите в интерпретаторе следующие команды (на примере установки модуля Some::Module версии 4.54):

% gunzip Some-Module-4 54 tar gz

% tar xf Some-Module-4 54

% cd Sone-Module-4 54

% perl Makefile PL

% make

% make test

% make install

Комментарий

Модули Perl, как и больщинство программ в Сети, распространяются в архивах tar, сжатых программой GNU zip. Если tar выдает предупреждение об ошибках контрольных сумм каталогов ( Directory checksum errors"), значит, вы испортили двоичный файл, приняв его в текстовом формате.

Вероятно, для установки модуля в системные каталоги необходимо стать привилегированным пользователем с соответствующими правами доступа. Стандартные модули обычно устанавливаются в каталог /usr/lib/perl5, а прочие - в каталог /usr/lib/perl5/site perl.

Рассмотрим процесс установки модуля MD5:

% gunzip MD5-1 7 tar gz % tar xf MD5-1 7 tar % cd M05-1 7 % per]. Makefile PL

Checking if your kit is complete... Looks good

Writing Makefile for MD5 % make

mkdir ./blib

mkdir ./blib/lib

cp MDS.pm ./bllb/llb/MD5.pin

AutoSplitting MD5 (./blib/lib/nuto/MDS)

/usr/bin/perl -I/usr/looal/llb/perl5/i386 ...

cp MDS.bs ./bllb/aroh/auto/MD5/MD5.bs

chmod 644 ./blib/aroh/auto/MD5/MD5.bsinkdir ./blib/manS

Manifying ./blib/manS/MDS.3

% make test

PERL DL N0NLAZY=1 /usr/bin/perl -I./blib/aroh -I./blib/lib -I/usr/looal/lib/perl5/i386-freebsd/5.00404 -I/usr/looal/lib/perl5 test.pi