?

Log in

No account? Create an account
Предыдущий пост Поделиться Следующий пост
Нужен перлдок
Рыжий
shoorick
Программам нужна документация и чем программа больше — тем сильнее эта самая документация нужна. Для некоторых языков программирования существует возможность генерировать документацию на основе имеющихся комментариев при помощи специальных программ. В перле подобная возможность — создавать документацию из комментариев — тоже есть, но здесь не требуются какие-то сторонние программы — всё уже сразу есть. Речь идёт о POD — Plain Old Documentation format — языке разметки для документирования перла, перловых программ и перловых модулей — текст, размеченный с его помощью, можно сразу в скрипты вставлять. Подробнее написано в man perlpod.

Можно сделать и так, чтоб консольное перловое приложение выводило документацию о себе, если запущено с определёнными аргументами, например, -?, -h или --help вызывало бы вывод краткой информации, а -m, --man или --manual — полной. Делается это так:
#!/usr/bin/perl

=head1 SYNOPSIS

./script-name.pl I<[options]>

=head1 OPTIONS

... ещё документация

=cut

use Getopt::Long;
use Pod::Usage qw( pod2usage );

my $need_help;
my $need_manual;

GetOptions(
    # обработка других аргументов
    'help|?'            => \$need_help,
    'manual'            => \$need_manual,
);

pod2usage(1)
    if $need_help;
pod2usage('verbose' => 2)
    if $need_manual;

Запускаем с аргументом -? — видим краткую справку, пробуем -m — видим что попало: где-то видна документация, а где-то — исходный код. Если после выхода из просмотра этого кода внимательнее посмотреть на экран, можно заметить сообщение
You need to install the perl-doc package to use this program.

Причина — отсутствие перлдока. В некоторых системах, например, во FreeBSD, perldoc сразу установлен, в других, таких как Debian — нет, и его надо ставить отдельно. Если поставить perldoc, то и скрипты начинают нормально выводить свою документацию:

$ perldoc ./script-name.pl
You need to install the perl-doc package to use this program.
$ sudo apt install perl-doc
...
$ ./script-name.pl --man
SYNOPSIS
./script-name.pl [options]
...


http://shoorick.ru/2018/01/26/perldoc-needed/

Записи из этого журнала по тегу «perl»

  • Надо ругаться в боевом режиме

    В состав перлового микрофреймворка Mojolicious::Lite входит класс Mojo::Log, который не просто пишет сообщения в лог, а ещё и учитывает важность…

  • Вместо себя

    Есть ненулевая вероятность того, что приближающийся 2019 год будет для моей семьи не таким, как сейчас и я в силу разных причин не смогу быть там,…

  • Больше перловой документации!

    Документация по языку Perl и его модулям теперь доступна и на  perldoc.pl, только оно без прокси не работает, ибо заблокировано роскомпозором.…


  • 1

До сих пор пишут

Ладно ещё на перле! Я вон год назад у коллег в соседнем отделе видел Delphi.

  • 1