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

Dополнительное описание поиска по элементу.

-t

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

-u

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

-m module

Отображение всего модуля: и кода, и неформатированной документации 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

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

-d destination-filename

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

-o output-formatname

Указывает, что 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 module-name

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

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

-w option:value или -w option

Указывает параметр для вызова форматировщика w с. Например, -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 language_code

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

PageName|ModuleName|ProgramName|URL

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

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

-n some-formatter

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

-r

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

-i

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

-V

Отображает версию используемого perldoc.

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

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

См. параметр -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

АВТОР

Текущий основной разработчик: Mark Allen <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>, и многие другие.