pod2man

СОДЕРЖАНИЕ

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

ИМЯ

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

СИНТАКСИС

pod2man [--center=string] [--date=string] [--errors=style] [--fixed=font] [--fixedbold=font] [--fixeditalic=font] [--fixedbolditalic=font] [--name=name] [--nourls] [--official] [--release=version] [--section=manext] [--quotes=quotes] [--lquote=quote] [--rquote=quote] [--stderr] [--utf8] [--verbose] [input [output] ...]

pod2man --help

ОПИСАНИЕ

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

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

--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=font

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

--fixeditalic=font

Курсивный вариант шрифта с фиксированной шириной символов (на самом деле, скорее всего, наклонный, так как у большинства шрифтов с фиксированной шириной есть только наклонный вариант, а не курсивный). По умолчанию 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)

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

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