Нужен перлдок
Программам нужна документация и чем программа больше - тем сильнее эта самая документация нужна. Для некоторых языков программирования существует возможность генерировать документацию на основе имеющихся комментариев при помощи специальных программ. В перле подобная возможность - создавать документацию из комментариев - тоже есть, но здесь не требуются какие-то сторонние программы - всё уже сразу есть. Речь идёт о 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/
Можно сделать и так, чтоб консольное перловое приложение выводило документацию о себе, если запущено с определёнными аргументами, например, -?, -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/