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