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-тире, исправляет «парные кавычки» и выполняет несколько других трофф-специфических настроек. Полную информацию см. в 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=шрифт

Шрифт с фиксированной шириной для использования для текста и кода verbatim. По умолчанию 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-последовательность escape, которая пытается создать правильно акцентированный символ (по крайней мере, для вывода 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-2018 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.