pod2man

СОДЕРЖАНИЕ

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

ИМЯ

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

СИНТАКСИС

pod2man [--center=строка] [--date=строка] [--errors=стиль] [--fixed=шрифт] [--fixedbold=шрифт] [--fixeditalic=шрифт] [--fixedbolditalic=шрифт] [--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).

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

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

pod2man предполагает, что ваши *roff-форматеры имеют шрифт с фиксированной шириной под названием CW. Если у вас он называется иначе (например, CR), используйте --fixed для его указания. Это обычно важно только для вывода troff для печати. Аналогично, вы можете задать шрифты, используемые для полужирного, курсивного и полужирного курсивного вывода с фиксированной шириной.

Помимо очевидных преобразований POD, Pod::Man, а следовательно, и pod2man также заботится о форматировании func(), func(n) и простых переменных ссылок, таких как $foo или @bar, поэтому вам не нужно использовать экранирования кода для них; сложные выражения, такие как $fred{'stuff'}, по-прежнему должны быть экранированы. Он также преобразует дефисы, которые не используются как тире, в en-дефисы, преобразует длинные дефисы--например, такой--в правильные em-дефисы, исправляет «парные кавычки» и выполняет несколько других корректировок, специфичных для troff. См. Pod::Man для получения полной информации.

ПАРАМЕТРЫ

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

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

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

Устанавливает строку нижнего колонтитула слева для макроса .TH в значение строка. По умолчанию используется дата изменения входного файла, или текущая дата, если вход получен из STDIN, и она будет основана на UTC (чтобы выход был воспроизводимым независимо от часового пояса).

--errors=стиль

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

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

--fixed=шрифт

Шрифт с фиксированной шириной символов для использования в тексте и коде. По умолчанию CW. Некоторые системы могут потребовать CR вместо этого. Важно только для вывода troff(1).

--fixedbold=шрифт

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

--fixeditalic=шрифт

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

--fixedbolditalic=шрифт

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

-h, --help

Выводит информацию об использовании.

-l, --lax

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

--lquote=кавычки

--rquote=кавычки

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

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

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

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

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

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

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

--nourls

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

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

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

foo <http://example.com/>

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

-o, --official

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

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

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

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

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

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

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

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

-s строка, --section=строка

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

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

--stderr

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

-u, --utf8

По умолчанию pod2man создаёт наиболее консервативный возможный вывод *roff, чтобы обеспечить его работу с как можно большим числом реализаций *roff. Многие реализации *roff не могут обрабатывать символы, не являющиеся ASCII, поэтому это означает, что все символы, не являющиеся ASCII, преобразуются либо в последовательность эскейпов *roff, которая пытается создать правильно акцентированный символ (по крайней мере, для вывода troff), либо в X.

Этот параметр указывает на вывод литеральных символов UTF-8. Если ваша реализация *roff может это обработать, это лучший формат вывода, и он предотвращает повреждение документов, содержащих символы, не являющиеся ASCII. Однако будьте осторожны, так как исходный код *roff с литеральными символами UTF-8 не поддерживается во многих реализациях и может даже привести к сегменту и другим нежелательным результатам.

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

-v, --verbose

Выводит имя каждого создаваемого выходного файла.

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

Пока все обработанные документы генерируют какой-либо вывод, даже если этот вывод содержит исправления (раздел 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<> директив. См. Pod::Man для получения дополнительной информации.

ОШИБКИ

Большая часть этой документации дублируется из Pod::Man.

АВТОР

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

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

Авторские права 1999-2001, 2004, 2006, 2008, 2010, 2012-2019 Russ Allbery <rra@cpan.org>

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

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

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

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

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