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 модуль

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

Указывает, что вывод не будет отправлен ни в пайп, ни в 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 параметр:значение или -w параметр

Указывает параметр для вызова форматировщика with. Например, -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. (Последнее предназначено для того, чтобы встроенные pod-файлы для исполняемых файлов, такие как сам 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> Адриан Р. Феррейра <ferreira@cpan.org>, Шон М. Бёрк <sburke@cpan.org>, Кеннет Албановски <kjahds@kjahds.com>, Энди Даффи <doughera@lafcol.lafayette.edu>, и многие другие.