perldoc

СОДЕРЖАНИЕ

• ИМЯ
• СИНТАКСИС
• ОПИСАНИЕ
• ПАРАМЕТРЫ
• БЕЗОПАСНОСТЬ
• СРЕДА
• ИЗМЕНЕНИЯ
• СМОТРИТЕ ТАКЖЕ
• АВТОР

ИМЯ

perldoc - Поиск документации Perl в формате Pod.

СИНТАКСИС

perldoc [-h] [-D] [-t] [-u] [-m] [-l] [-U] [-F]
    [-i] [-V] [-T] [-r]
    [-d destination_file]
    [-o formatname]
    [-M FormatterClassName]
    [-w formatteroption:value]
    [-n nroff-replacement]
    [-X]
    [-L language_code]
    PageName|ModuleName|ProgramName|URL

Примеры:

perldoc -f BuiltinFunction

perldoc -L it -f BuiltinFunction

perldoc -q FAQ Keyword

perldoc -L fr -q FAQ Keyword

perldoc -v PerlVariable

perldoc -a PerlAPI

Подробное описание переключателей см. ниже.

ОПИСАНИЕ

perldoc ищет документацию в формате .pod, встроенную в дерево установки perl или в скрипт perl, и отображает её с помощью различных форматировщиков. Это в основном используется для документации модулей библиотеки perl.

На вашем системе также могут быть установлены man-страницы для этих модулей, в этом случае вы можете просто использовать команду man(1).

Если вам нужна таблица содержания документации модулей библиотеки Perl, обратитесь к странице perltoc.

ПАРАМЕТРЫ

-h

Выводит краткое сообщение help.

-D

Dетальный поиск по заданному dетали.

-t

Отображает документацию с помощью простого текстового конвертера, а не nroff. Это может быть быстрее, но, вероятно, будет выглядеть не так красиво.

-u

Пропустить реальное форматирование Pod и просто показать исходный код Pod (Uнеформатированный)

-m модуль

Отображает весь модуль: код и неформатированную документацию pod. Это может быть полезно, если документация не объясняет функцию в достаточной детали, и вы хотите непосредственно просмотреть код; perldoc найдет файл для вас и просто передаст его для отображения.

-l

Отображает только имя файла найденного модуля.

-U

При запуске от суперпользователя не пытаться понизить привилегии для безопасности. Этот параметр подразумевается с -F.

ПРИМЕЧАНИЕ: Более подробная информация приведена в разделе БЕЗОПАСНОСТЬ ниже.

-F

Рассматривать аргументы как имена файлов; поиск по каталогам не будет производиться. Подразумевает -U, если запущен от суперпользователя.

-f perlfunc

Параметр -f, за которым следует имя встроенной функции perl, извлечёт документацию этой функции из perlfunc.

Пример:

perldoc -f sprintf

-q perlfaq-search-regexp

Параметр -q принимает регулярное выражение в качестве аргумента. Он будет искать заголовки вопросов в perlfaq[1-9] и выводить записи, соответствующие регулярному выражению.

Пример:

perldoc -q shuffle

-a perlapifunc

Параметр -a, за которым следует имя функции perl api, извлечёт документацию этой функции из perlapi.

Пример:

perldoc -a newHV

-v perlvar

Параметр -v, за которым следует имя предопределённой переменной Perl, извлечёт документацию этой переменной из perlvar.

Примеры:

perldoc -v '$"'
perldoc -v @+
perldoc -v DATA

-T

Указывает, что вывод не должен отправляться на pager, а должен быть отправлен напрямую в STDOUT.

-d имя_файла_назначения

Указывает, что вывод не должен отправляться ни на pager, ни в STDOUT, а должен быть сохранён в указанном файле. Пример: perldoc -oLaTeX -dtextwrapdocs.tex Text::Wrap

-o имя_формата_вывода

Указывает, что вы хотите, чтобы Perldoc попробовал использовать класс форматирования Pod для указанного вами формата вывода. Например: -oman. Это фактически просто оболочка вокруг параметра -M; использование -oformatname просто ищет загружаемый класс, добавляя это имя формата (с разными регистрами) к концу разных префиксов имени класса.

Например, -oLaTeX в настоящее время пытается использовать все следующие классы: Pod::Perldoc::ToLaTeX Pod::Perldoc::Tolatex Pod::Perldoc::ToLatex Pod::Perldoc::ToLATEX Pod::Simple::LaTeX Pod::Simple::latex Pod::Simple::Latex Pod::Simple::LATEX Pod::LaTeX Pod::latex Pod::Latex Pod::LATEX.

-M имя_модуля

Указывает модуль, который вы хотите использовать для форматирования pod. Класс должен как минимум предоставлять метод parse_from_file. Например: perldoc -MPod::Perldoc::ToChecker.

Вы можете указать несколько классов, объединив их запятыми или точками с запятой, как в -MTk::SuperPod;Tk::Pod.

-w option:value или -w option

Указывает параметр для вызова форматировщика с. Например, -w textsize:15 вызовет $formatter->textsize(15) на объекте форматировщика перед его использованием для форматирования объекта. Для того, чтобы это было допустимо, класс форматировщика должен предоставлять такой метод, а передаваемое вами значение должно быть допустимым. (Если textsize ожидает целое число, а вы делаете -w textsize:big, ожидайте проблем.)

Вы можете использовать -w optionname (без значения) как сокращение для -w optionname:TRUE. Предположительно, это полезно в случаях функций включения/выключения, таких как: -w page_numbering.

Вы можете использовать знак "=" вместо ":", как в: -w textsize=15. Это может быть более (или менее) удобным, в зависимости от используемой оболочки.

-X

Использовать индекс, если он присутствует. Параметр -X ищет запись, имя которой соответствует имени, заданному в командной строке, в файле $Config{archlib}/pod.idx. Файл pod.idx должен содержать полные пути к файлам, по одному на строке.

-L код_языка

Это позволяет указать код языка для желаемого перевода. Если пакет POD2::<language_code> не установлен на вашей системе, этот переключатель игнорируется. Все доступные пакеты переводов находятся в пространстве имен POD2::. Обратитесь к POD2::IT (или POD2::FR), чтобы узнать, как создать новые локализованные пакеты документации POD2::* и интегрировать их в Pod::Perldoc.

ИмяСтраницы|ИмяМодуля|ИмяПрограммы|URL

Элемент, который вы хотите найти. Вложенные модули (такие как File::Basename) задаются либо как File::Basename или File/Basename. Вы также можете указать описательное имя страницы, например perlfunc. Для URL, поддерживаются только HTTP и HTTPS.

Для простых имён, как 'foo', когда обычный поиск не находит соответствующую страницу, выполняется поиск с префиксом "perl". Таким образом, "perldoc intro" достаточно для поиска/отображения "perlintro.pod".

-n некоторый_форматировщик

Указать замену для groff

-r

Рекурсивный поиск.

-i

Игнорировать регистр.

-V

Отображает версию perldoc, которую вы используете.

БЕЗОПАСНОСТЬ

Поскольку perldoc не работает должным образом с tainted данными и известен своими проблемами безопасности, при запуске от суперпользователя он попытается понизить привилегии, установив эффективный и реальный идентификаторы на учётную запись nobody или nouser, или -2, если недоступно. Если он не сможет отказаться от своих привилегий, он не запустится.

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

С версии 3.26, использование -F в режиме суперпользователя также подразумевает -U, так как открытие большинства файлов и навигация по каталогам требуют привилегий, превышающих уровень nobody/nogroup.

СРЕДА

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

Полезные значения для PERLDOC включают -oterm, -otext, -ortf, -oxml, и так далее, в зависимости от имеющихся модулей; или класс форматирования может быть указан точно, как -MPod::Perldoc::ToTerm или аналогично.

perldoc также ищет каталоги, указанные в переменных среды PERL5LIB (или PERLLIB, если PERL5LIB не определено) и PATH. (Последнее — для того, чтобы встроенные под-файлы для исполняемых файлов, например, сам perldoc, были доступны.)

В каталогах, где существуют Makefile.PL или Build.PL, perldoc добавит . и lib в первую очередь в свой путь поиска, а пока вы не являетесь суперпользователем, также добавит blib. Это действительно полезно, если вы работаете внутри каталога сборки и хотите просмотреть документацию, даже если у вас установлена предыдущая версия модуля.

perldoc будет использовать, в порядке приоритета, pager, определённый в PERLDOC_PAGER, MANPAGER, или PAGER перед тем, как попытаться найти pager самостоятельно. (MANPAGER не используется, если perldoc было сказано отобразить простой текст или неформатированный pod.)

При использовании perldoc в режиме -m (отображение исходного кода модуля), perldoc попытается использовать pager, установленный в PERLDOC_SRC_PAGER. Полезное значение для этой команды — ваш любимый редактор, как в /usr/bin/nano. (Не судите меня.)

Полезное значение для PERLDOC_PAGER — less -+C -E.

Установление PERLDOCDEBUG в положительное целое число заставит perldoc генерировать ещё более подробный вывод, чем -D.

ИЗМЕНЕНИЯ

До версии 3.14_05 переключатель -v использовался для вывода подробных сообщений об операциях perldoc, теперь он активируется при помощи -D.

СМОТРИТЕ ТАКЖЕ

perlpod, Pod::Perldoc

АВТОР

Текущий основной разработчик: Марк Аллен <mallen@cpan.org>

Предыдущие участники: brian d foy <bdfoy@cpan.org> Adriano R. Ferreira <ferreira@cpan.org>, Sean M. Burke <sburke@cpan.org>, Kenneth Albanowski <kjahds@kjahds.com>, Andy Dougherty <doughera@lafcol.lafayette.edu>, и многие другие.