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

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

-u

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

-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

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

-d destination-filename

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

См. параметр -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>, и многие другие.