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

Выводит краткое сообщение спомощью.

-D

Подробное описание поиска по заданному элементу.

-t

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

-u

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

-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, за которым следует имя функции API Perl, извлечёт документацию этой функции из perlapi.

Пример:

perldoc -a newHV

-v perlvar

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

Примеры:

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

-T

Указывает, что вывод не будет направлен в пейджер, а будет направлен непосредственно в стандартный вывод.

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

Указывает, что вывод не должен направляться ни в пейджер, ни в стандартный вывод, а должен быть сохранён в указанном имени файла. Пример: 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

Указывает параметр для вызова форматировщика c помощью. Например, -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 не работает должным образом с незащищенными данными и известен проблемами безопасности, при запуске с правами суперпользователя он попытается понизить привилегии, установив эффективный и реальный идентификаторы на счёт 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 будет использовать пейджер, определённый в PERLDOC_PAGER, MANPAGER, или PAGER, в порядке предпочтения, прежде чем пытаться найти пейджер самостоятельно. (MANPAGER не используется, если perldoc было указано отображать обычный текст или неформатированный pod.)

При использовании perldoc в режиме -m (отображение исходного кода модуля), perldoc попытается использовать пейджер, установленный в 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>, и многие другие.