Shoorick (shoorick) wrote,
Shoorick
shoorick

Category:

Нужен перлдок

Программам нужна документация и чем программа больше — тем сильнее эта самая документация нужна. Для некоторых языков программирования существует возможность генерировать документацию на основе имеющихся комментариев при помощи специальных программ. В перле подобная возможность — создавать документацию из комментариев — тоже есть, но здесь не требуются какие-то сторонние программы — всё уже сразу есть. Речь идёт о 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/
Tags: freebsd, linux, perl, perldoc, unix, документация, программизм
Subscribe

Posts from This Journal “perl” Tag

  • Цветной Subversion

    Git умеет «из коробки» раскрашивать то, что выводит в консоль, а Subversion — нет. Надоело руками каждый раз перенаправлять вывод svn diff в…

  • Тестирование в моджо — только через прув

    Из перлового веб-фреймворка Mojolicious начиная с вышедшей ровно четыре месяца назад версии 8.0 убрана команда test Теперь вместо этой…

  • Правильный тип для офисных файлов

    Перловый микрофреймворк Mojolicious::Lite умеет сам выдавать существующие файлы, но при этом не все из них получают верный тип содержимого…

  • Post a new comment

    Error

    default userpic

    Your reply will be screened

    Your IP address will be recorded 

    When you submit the form an invisible reCAPTCHA check will be performed.
    You must follow the Privacy Policy and Google Terms of use.
  • 3 comments