pod2man

СОДЕРЖАНИЕ

• ИМЯ
• СИНТАКСИС
• ОПИСАНИЕ
• ПАРАМЕТРЫ
• СТАТУС ВЫХОДА
• ДИАГНОСТИКА
• ПРИМЕРЫ
• АВТОР
• АВТОРСКИЕ ПРАВА И ЛИЦЕНЗИЯ
• СМОТРИТЕ ТАКЖЕ

ИМЯ

pod2man - Преобразование данных POD в форматированный ввод *roff

СИНТАКСИС

pod2man [--center=строка] [--date=строка] [--encoding=кодировка] [--errors=стиль] [--fixed=шрифт] [--fixedbold=шрифт] [--fixeditalic=шрифт] [--fixedbolditalic=шрифт] [--guesswork=правило[,правило...]] [--name=имя] [--nourls] [--official] [--release=версия] [--section=manext] [--quotes=кавычки] [--lquote=кавычка] [--rquote=кавычка] [--stderr] [--utf8] [--verbose] [вход [выход] ...]

pod2man --help

ОПИСАНИЕ

pod2man — это скрипт-обёртку вокруг модуля Pod::Man, использующий его для генерации ввода *roff из исходного кода POD. Полученный код *roff подходит для отображения на терминале с помощью nroff(1), обычно через man(1), или для печати с помощью troff(1).

По умолчанию (на системах, не использующих EBCDIC), pod2man выводит страницы руководства в кодировке UTF-8. Вывод должен работать с программой man на системах, использующих groff (большинство дистрибутивов Linux) или mandoc (большинство вариантов BSD), но может привести к искажённому выводу на более старых UNIX-системах. Чтобы выбрать другую, возможно, более обратной совместимой вывод кодировки на таких системах, используйте --encoding=roff\. (по умолчанию в более ранних версиях Pod::Man). Смотрите опцию --encoding и "ENCODING" в Pod::Man для получения более подробной информации.

вход — файл для чтения исходного кода POD (POD может быть вставлен в код). Если вход не указан, по умолчанию используется STDIN. выход, если указан, — файл, в который записывается отформатированный вывод. Если выход не указан, отформатированный вывод записывается в STDOUT. Несколько файлов POD могут быть обработаны в одном вызове pod2man (чтобы сэкономить время загрузки и компиляции модулей), предоставив на командной строке несколько пар вход и выход файлов.

--section, --release, --center, --date и --official можно использовать для установки заголовков и подвалов, которые нужно использовать. Если не указаны, Pod::Man использует различные значения по умолчанию. Подробности см. ниже.

ПАРАМЕТРЫ

Каждый параметр снабжён аннотацией с указанием версии podlators, в которой данный параметр был добавлен, и его текущим значением.

-c строка, --center=строка

[1.00] Устанавливает центрированный заголовок страницы для макроса .TH в значение строка. По умолчанию используется User Contributed Perl Documentation, но также см. --official ниже.

-d строка, --date=строка

[4.00] Устанавливает строку левого подвала для макроса .TH в значение строка. По умолчанию используется первое значение из POD_MAN_DATE, SOURCE_DATE_EPOCH, даты изменения входного файла или текущей даты (если вход поступает из STDIN), и дата будет в формате UTC. Для получения более подробной информации см. "CLASS METHODS" в Pod::Man.

-e кодировка, --encoding=кодировка

[5.00] Указывает кодировку вывода. кодировка должна быть кодировкой, распознаваемой модулем Encode (см. Encode::Supported). По умолчанию на системах, не использующих EBCDIC, используется UTF-8.

Если вывод содержит символы, которые не могут быть представлены в этой кодировке, это ошибка, которая будет отображаться в соответствии с настройкой опции --errors. Если обработка ошибок отличается от die, непредставимый символ будет заменён символом подстановки Encode (обычно ?).

Если опция encoding установлена в специальное значение groff (по умолчанию на системах EBCDIC) или если модуль Encode недоступен, а кодировка установлена на любое значение, отличное от roff (см. ниже), Pod::Man преобразует все символы, не являющиеся ASCII, в \[uNNNN] Unicode-экранированные символы. Обычно они не являются частью языка *roff, но поддерживаются groff и mandoc, а значит, и большинством современных процессоров страниц руководств.

Если кодировка установлена в специальное значение roff, pod2man выполнит историческое преобразование (некоторых) символов ISO 8859-1 в *roff-экранированные символы, которые могут быть адекватны в troff и читаемы (хотя и некрасивы) в nroff. Это было поведением по умолчанию в версиях pod2man до 5.00. При этой кодировке все остальные символы, не являющиеся ASCII, будут заменены на X. Это может потребоваться для очень старых реализаций troff и nroff, которые не поддерживают UTF-8, но представление любых символов, не являющихся ASCII, в нём очень плохое и часто специфично для европейских языков. Его использование не рекомендуется.

ВНИМАНИЕ: Кодировка входного исходного POD независима от кодировки вывода, и установка этого параметра не влияет на интерпретацию входного POD. Если ваш исходный POD не в US-ASCII, его кодировка должна быть объявлена с помощью команды =encoding в исходном коде. Если этого не сделано, Pod::Simple попытается угадать кодировку и может преуспеть, если это Latin-1 или UTF-8, но при этом будут выведены предупреждения. Для получения дополнительной информации см. perlpod(1).

--errors=стиль

[2.5.0] Устанавливает стиль обработки ошибок. die означает выброс исключения при любой ошибке форматирования POD. stderr означает вывод сообщений об ошибках в стандартный поток ошибок, но не выброс исключения. pod означает включение раздела POD ERRORS в результирующей документации, обобщающего ошибки. none полностью игнорирует ошибки POD, насколько это возможно.

По умолчанию используется die.

--fixed=шрифт

[1.0] Шрифт с фиксированной шириной символов для использования для текста verbatim и кода. По умолчанию CW. Некоторые системы могут предпочесть CR. Важно только для вывода troff.

--fixedbold=шрифт

[1.0] Жирный вариант шрифта с фиксированной шириной символов. По умолчанию CB. Важно только для вывода troff.

--fixeditalic=font

[1.0] Курсивный вариант шрифта с фиксированной шириной символов (некоторое неудачное название, так как большинство шрифтов с фиксированной шириной имеют только наклонный, а не курсивный вариант). По умолчанию CI. Важно только для вывода troff.

--fixedbolditalic=шрифт

[1.0] Жирный курсивный (в теории, скорее всего, наклонный на практике) вариант шрифта с фиксированной шириной символов. Pod::Man не предполагает, что у вас есть такой, и по умолчанию используется CB. Некоторые системы (например, Solaris) имеют этот шрифт как CX. Важно только для вывода troff.

--guesswork=правило[,правило...]

[5.00] По умолчанию pod2man применяет некоторые стандартные правила форматирования, основанные на предположениях и регулярных выражениях, которые предназначены для упрощения написания документации Perl и требуют меньше явного разметки. Эти правила могут не всегда быть подходящими, особенно для документации, не относящейся к Perl. Эта опция позволяет отключить все или некоторые из них.

Специальное правило all включает все предположения. Это также по умолчанию по соображениям обратной совместимости. Специальное правило none отключает все предположения. В противном случае значение этой опции должно быть запятой, разделённым списком одного или нескольких из следующих ключевых слов:

functions

Преобразовать ссылки на функции, например foo(), в жирный шрифт, даже если они не имеют разметки. Имя функции принимает допустимые символы Perl для имён функций (включая :), а заключённые скобки должны быть присутствующими и пустыми.

manref

Сделать первую часть (перед скобками) ссылок на страницы руководств, таких как foo(1), жирным шрифтом, даже если они не имеют разметки. Раздел должен быть одиночным числом, необязательно после которого следуют строчные буквы.

quoting

Если никакие предположения не включены, любой текст, заключённый в C<>, окружён двойными кавычками в выводе nroff (терминал), если содержимое уже не заключено в кавычки. При включённом предположении кавычки также будут подавлены для переменных Perl, имён функций, вызовов функций, чисел и шестнадцатеричных констант.

variables

Преобразовать имена переменных Perl в шрифт с фиксированной шириной, даже если они не имеют разметки. Это преобразование будет заметно только в выводе troff или другом формате вывода (в отличие от вывода терминала nroff), который поддерживает шрифты с фиксированной шириной.

Любое неизвестное имя предположения будет проигнорировано (для потенциальной будущей совместимости), поэтому будьте внимательны к написанию.

-h, --help

[1.00] Вывести информацию о использовании.

-l, --lax

[1.00] Больше не используется. pod2man раньше проверял свою входную информацию на валидность как страницу руководства, но теперь это должно делаться с помощью podchecker(1) вместо этого. Принимается для обратной совместимости; эта опция больше ничего не делает.

--language=язык

[5.00] Добавить команды, указывающие groff, что входной файл написан на заданном языке. Значение этого параметра должно быть сокращённым обозначением языка, для которого groff предоставляет дополнительную конфигурацию, например ja (для японского языка) или zh (для китайского языка).

Это добавит:

.mso <language>.tmac
.hla <language>

в начало файла, что настраивает правильный перенос строк для указанного языка. Без этих команд groff может не знать, как добавить правильный перенос строк для китайского и японского текста, если страница руководства установлена в обычный каталог страниц руководств, такой как /usr/share/man.

Во многих системах это будет выполнено автоматически, если страница руководства установлена в каталог страниц руководств, специфичный для языка, такой как /usr/share/man/zh_CN. В этом случае эта опция не требуется.

К сожалению, команды, добавленные с помощью этого параметра, специфичны для groff и не будут работать с другими реализациями troff и nroff.

--lquote=кавычка

--rquote=кавычка

[4.08] Устанавливает кавычки, используемые для окружения текста C<>. --lquote устанавливает левую кавычку, а --rquote — правую. Любая из них также может быть установлена в специальное значение none, в этом случае кавычка не добавляется с этой стороны текста C<> (но шрифт всё ещё меняется для вывода troff).

См. также опцию --quotes, которая может использоваться для одновременной установки обеих кавычек. Если установлены и --quotes, и одна из других опций, --lquote или --rquote переопределяет --quotes.

-n имя, --name=имя

[4.08] Устанавливает имя страницы руководства для макроса .TH в значение имя. Без этой опции имя руководства устанавливается в верхнем регистре базового имени преобразуемого файла, если раздел руководства не равен 3, в этом случае анализируется путь, чтобы определить, является ли он путём к модулю Perl. Если это так, путь вроде .../lib/Pod/Man.pm преобразуется в имя вроде Pod::Man. Эта опция, если задана, переопределяет любое автоматическое определение имени.

Хотя следовать этой конвенции необязательно, помните, что конвенция для страниц руководств UNIX заключается в том, что заголовок должен быть в верхнем регистре, даже если команда не является таковой. (Модули Perl традиционно используют смешанный регистр для заголовка страницы руководства, однако.)

Эта опция, вероятно, не полезна при одновременной обработке нескольких файлов POD.

При преобразовании исходного POD из стандартного ввода имя будет установлено в STDIN, если эта опция не указана. Настоятельно рекомендуется указать эту опцию для установки осмысленного имени страницы руководства.

--nourls

[2.5.0] Обычно форматирование L<> с URL, но с текстом-якорем форматируется для отображения как текста-якоря, так и URL. Другими словами:

L<foo|http://example.com/>

форматируется как:

foo <http://example.com/>

Этот флаг, если задан, подавляет URL при наличии текста-якоря, так что этот пример будет отформатирован только как foo. Это может привести к менее перегруженному выводу в тех случаях, когда URL не особенно важны.

-o, --official

[1.00] Установить заголовок по умолчанию, чтобы указать, что эта страница входит в стандартную версию Perl, если также не задана опция --center.

-q кавычки, --quotes=кавычки

[4.00] Устанавливает кавычки, используемые для окружения текста C<>, в кавычки. Если кавычки — одиночный символ, он используется как левая, так и правая кавычка. В противном случае он разделяется пополам, и первая половина строки используется как левая кавычка, а вторая — как правая.

кавычки также могут быть установлены в специальное значение none, в этом случае кавычки не добавляются вокруг текста C<> (но шрифт всё ещё меняется для вывода troff).

См. также опции --lquote и --rquote, которые могут использоваться для установки левой и правой кавычек независимо. Если установлены и --quotes, и одна из других опций, --lquote или --rquote переопределяет --quotes.

-r версия, --release=версия

[1.00] Установите выровненный по центру футер для макроса .TH на version. По умолчанию он устанавливается в версию Perl, под которой вы запускаете pod2man. Установка пустой строки приведет к тому, что некоторые *roff-реализации будут использовать системное значение по умолчанию.

Обратите внимание, что некоторые системные an макросы предполагают, что выровненный по центру футер будет датой последнего изменения и будет предваряться чем-то вроде Last modified: . Если это так для вашей целевой системы, вы можете установить --release на последнюю дату изменения и --date на номер версии.

-s string, --section=string

[1.00] Установите раздел для макроса .TH. Стандартная система нумерации разделов использует 1 для команд пользователя, 2 для системных вызовов, 3 для функций, 4 для устройств, 5 для форматов файлов, 6 для игр, 7 для разносторонней информации и 8 для команд администратора. Однако, здесь наблюдается большое разнообразие; некоторые системы (например, Solaris) используют 4 для форматов файлов, 5 для разносторонней информации и 7 для устройств. Другие используют 1m вместо 8 или некоторую смесь обоих. Практически единственные надежно согласованные номера разделов — 1, 2 и 3.

По умолчанию будет использоваться раздел 1, если файл не заканчивается на .pm, в противном случае будет выбран раздел 3.

--stderr

[2.1.3] По умолчанию pod2man завершается ошибкой, если в входных данных POD обнаружены ошибки. Если задан флаг --stderr и отсутствует флаг --errors, ошибки отправляются в стандартный поток ошибок, но pod2man не прерывается. Это эквивалентно --errors=stderr и поддерживается для обратной совместимости.

-u, --utf8

[2.1.0] Этот параметр использовался для указания pod2man на генерацию выходных данных в формате UTF-8. Поскольку сейчас это значение по умолчанию с версии 5.00, оно игнорируется и ничего не делает.

-v, --verbose

[1.11] Выводит имя каждого выходного файла по мере его генерации.

СТАТУС ВЫХОДА

Пока все обработанные документы приводят к какому-либо выводу, даже если этот вывод включает ошибки (раздел POD ERRORS сгенерированный с помощью --errors=pod), pod2man завершится со статусом 0. Если какой-либо из обрабатываемых документов не приводит к документу вывода, pod2man завершится со статусом 1. Если в документе POD, который обрабатывается, есть синтаксические ошибки, а стиль обработки ошибок установлен по умолчанию die, pod2man прервется немедленно со статусом выхода 255.

ДИАГНОСТИКА

Если pod2man завершается с ошибками, см. Pod::Man и Pod::Simple для получения информации о возможных причинах этих ошибок.

ПРИМЕРЫ

pod2man program > program.1
pod2man SomeModule.pm /usr/perl/man/man3/SomeModule.3
pod2man --section=7 note.pod > note.7

Если вы хотите непрерывно печатать многостраничную справку, вам, вероятно, нужно установить регистры C и D, чтобы установить непрерывную нумерацию страниц и чётность/нечётность страниц, по крайней мере, в некоторых версиях man(7).

troff -man -rC1 -rD1 perl.1 perldata.1 perlsyn.1 ...

Чтобы получить записи индекса для STDERR, включите регистр F, как в:

troff -man -rF1 perl.1

Индексирование просто выводит сообщения через .tm для каждой главной страницы, раздела, подраздела, пункта и любых X<> директив.

АВТОР

Russ Allbery <rra@cpan.org>, на основе оригинального pod2man от Larry Wall и Tom Christiansen.

АВТОРСКИЕ ПРАВА И ЛИЦЕНЗИЯ

Copyright 1999-2001, 2004, 2006, 2008, 2010, 2012-2019, 2022 Russ Allbery <rra@cpan.org>

Эта программа — свободное программное обеспечение; вы можете перераспределять ее и/или изменять ее на тех же условиях, что и Perl.

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

Pod::Man, Pod::Simple, man(1), nroff(1), perlpod(1), podchecker(1), perlpodstyle(1), troff(1), man(7)

Руководство по макросу, документирующему макрос, может быть man(5), а не man(7) в вашей системе.

Текущая версия этого скрипта всегда доступна на его веб-сайте по адресу https://www.eyrie.org/~eagle/software/podlators/. Он также входит в состав дистрибутива Perl с версии 5.6.0.