Есть ли способ повторно использовать текст в документации perlpod?

Question

У меня есть куча повторяющихся текстов в моей документации по perlpod. Конечно, я мог бы создать отдельный раздел и сослаться на него, но мне было интересно, есть ли способ ввести текст где-то один раз и вставить его в нескольких местах?

Не думаю, что это возможно, ноЯ хотел бы попросить убедиться, что я ничего не пропустил.

Или - может быть, есть лучшая техника документирования perl?

Answer 1

Как вы уже поняли, Pod - это (намеренно) очень простой язык разметки. Он не имеет каких-либо особенно сложных функций, и одна из вещей, которые ему не хватает, - это способ вставки текста из другого источника.

Я бы предложил переместить повторяющийся текст в его собственный раздел и создать ссылку на этот раздел. (используя L<...>) всякий раз, когда вы хотите сослаться на этот текст.

Answer 2

Несмотря на то, что разметка Pod является очень простой, нам не нужно буквально печатать все вручную.

Текст для документации можно обрабатывать обычным образом, используя любые инструменты Perl, которые вы пожелаете, чтобы создатьстрока с текстом в формате pod. Затем эту строку с Pod можно отобразить с помощью core Pod :: Usage , через файл (который можно удалить или сохранить) или напрямую с помощью core Pod :: Simple .

Показать строку Pod, написав файл

use warnings;
use strict;
use feature 'say';
use Path::Tiny;    # convenience, to "spew" a file    

my $man = shift;        
show_pod() if $man;
say "done $$";

sub show_pod {
    require Pod::Usage; Pod::Usage->import('pod2usage');

    my $pod_text = make_pod();
    my $pod_file = $0 =~ s/\.pl$/.pod/r;
    path($pod_file)->spew($pod_text);

    pod2usage( -verbose => 2, -input => $pod_file );  # exits by default
}

sub make_pod {
    my $repeated = q(lotsa text that gets repeated);
    my $doc_text = <<EOD;
=head1 NAME

$0 - demo perldoc

=head1 SYNOP...

Text that is also used elsewhere: $repeated...

=cut
EOD

    return $doc_text;
}

Файл .pod можно удалить: добавьте аргументы -exitval => 'NOEXIT' к pod2usage, чтобы он нене выходите, а затем удалите файл. Или, скорее, оставьте его доступным для других инструментов и применений.

В качестве подсказки я разделил задание на две подпрограммы, поскольку полезно иметь возможность писать только файл .pod, который затем можно использовать и просматривать другими способами и в разных форматах. ^† Это не нужно, чтобы просто показывать документы, и все операции с Pod можно выполнять в одной подпрограмме.

Отображать строку Pod напрямую

Если нет никакого желания хранить файл .pod, нам не нужно его делать

sub show_pod {
    my $pod_text = make_pod();

    require Pod::Simple::Text;
    Pod::Simple::Text->filter( \$pod_text );  # doesn't exit so add that
}

(остальная часть программы выше та же) Вызов ->filter являетсяярлык для создания объекта, установки дескриптора файла и обработки содержимого. Подробнее смотрите в документации.

Любой из этих подходов дает вам гораздо большую гибкость.

Кроме того, хотя можно действительно решить повторяющийся текст, ссылаясь на отдельный раздел с этим текстом, это, конечно, не позволяет нам использовать переменные или выполнять какую-либо обработку Perl - что все доступно, когда вы пишетестрока Pod, которая затем передается в perlpod для отображения.

---

^† Я использую такую ​​систему в большом проекте с файлами .pod в ихкаталог. Существует также простой отдельный скрипт для общего управления документацией, который вызывает отдельные программы с опциями для записи / обновления своих .pod s, в HTML с файлом стиля CPAN, для главной веб-страницы.

Любая программаконечно же, можно просто отобразить документы в нужном формате.