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'}, всё ещё нуждаются в экранировании. Он также преобразует тире, которые не используются как дефисы, в разделы, делает длинные тире--такие, как это--в правильные 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=шрифт

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

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

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

Если все обработанные документы приводят к какому-либо выводу, даже если этот вывод включает в себя errata (раздел POD ERRORS, сгенерированный с помощью --errors=pod), pod2man завершится с кодом 0. Если любой из обрабатываемых документов не приводит к документу вывода, 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.

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

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

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

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

АВТОР

Расс Алберри <rra@cpan.org>, основанный очень сильно на оригинальном pod2man Ларри Уолла и Тома Кристиана.

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

Авторские права 1999, 2000, 2001, 2004, 2006, 2008, 2010, 2012, 2013, 2014, 2015, 2016, 2017 Расс Алберри <rra@cpan.org>

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