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::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, не приводит к документу вывода, pod2man завершится с кодом 1. Если в документе POD, обрабатываемом pod2man, есть синтаксические ошибки, и стиль обработки ошибок установлен по умолчанию (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.