pod2text

СОДЕРЖАНИЕ

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

НАЗВАНИЕ

pod2text - Преобразование данных POD в форматированный ASCII текст

СИНТАКСИС

pod2text [-aclostu] [--code] [--errors=style] [-i indent] [-q quotes] [--nourls] [--stderr] [-w width] [input [output ...]]

pod2text -h

ОПИСАНИЕ

pod2text — это фронтенд для Pod::Text и его подклассов. Он использует их для генерации форматированного ASCII текста из исходного кода POD. Он может по желанию использовать последовательности termcap или ANSI escape-последовательности для форматирования текста.

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

ПАРАМЕТРЫ

-a, --alt

Используйте альтернативный формат вывода, который, помимо прочего, использует другой стиль заголовков и помечает записи =item двоеточием в левом отступе.

--code

Включите любой текст, не являющийся POD, из входного файла в выходной файл также. Полезно для просмотра кода, документированного с помощью блоков POD, с рендерингом POD и сохранением кода неизменным.

-c, --color

Отформатируйте вывод с помощью ANSI escape-последовательностей. Использование этого параметра требует, чтобы Term::ANSIColor был установлен на вашей системе.

--errors=style

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

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

-i indent, --indent=indent

Установите количество пробелов для отступа обычного текста и для отступа по умолчанию для блоков =over. По умолчанию используется 4 пробела, если этот параметр не указан.

-h, --help

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

-l,-loose

Выводить пустую строку после заголовка =head1. Обычно после =head1 пустая строка не выводится, хотя она по-прежнему выводится после =head2, так как это ожидаемый формат для страниц руководств; если вы форматируете произвольные текстовые документы, рекомендуется использовать этот параметр.

-m width, --left-margin=width, --margin=width

Ширина левого отступа в пробелах. По умолчанию 0. Это отступ для всего текста, включая заголовки, а не количество, на которое отступается обычный текст; для последнего см. параметр -i.

--nourls

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

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

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

foo <http://example.com/>

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

-o, --overstrike

Отформатировать вывод с наложением печати. Жирный текст отображается как символ, возврат, символ. Курсив и имена файлов отображаются как подчеркивание, возврат, символ. Многие программы просмотра, такие как less, знают, как преобразовать это в жирный или подчеркнутый текст.

-q quotes, --quotes=quotes

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

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

-s, --sentence

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

--stderr

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

-t, --termcap

Попробуйте определить ширину экрана и последовательности жирного и подчеркнутого текста для терминала из termcap и используйте эту информацию для форматирования вывода. Вывод будет обрезаться на две колонки меньше, чем ширина устройства вашего терминала. Для использования этого параметра требуется, чтобы на вашей системе был файл termcap, где Term::Cap может его найти, и требуется, чтобы ваша система поддерживала termios. С этим параметром вывод pod2text будет содержать управляющие последовательности терминала для вашего текущего типа терминала.

-u, --utf8

По умолчанию pod2text пытается использовать тот же кодировку вывода, что и кодировку входа (для обеспечения обратной совместимости со старыми версиями). Этот параметр указывает на то, что кодировка вывода должна быть UTF-8.

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

-w, --width=width, -width

Столбец, на котором необходимо обрезать текст справа. По умолчанию 76, если не задан -t, в этом случае он на две колонки меньше ширины устройства вашего терминала.

КОД ВЫХОДА

Пока все обработанные документы дают какой-либо результат, даже если этот результат включает ошибки (раздел POD ERRORS, сгенерированный с --errors=pod), pod2text завершится со статусом 0. Если ни один из обрабатываемых документов не приводит к документу вывода, pod2text завершится со статусом 1. Если в документе POD, обрабатываемом, есть синтаксические ошибки, и стиль обработки ошибок установлен по умолчанию die, pod2text немедленно прервётся с кодом выхода 255.

ДИАГНОСТИКА

Если pod2text завершается с ошибками, см. Pod::Text и Pod::Simple для получения информации о том, что эти ошибки могут означать. Внутренне он также может генерировать следующую диагностику:

-c (--color) требует, чтобы Term::ANSIColor был установлен

(F) -c или --color были заданы, но Term::ANSIColor не удалось загрузить.

Неизвестный параметр: %s

(F) Был задан неизвестный параметр командной строки.

Кроме того, другие сообщения об ошибках Getopt::Long могут возникнуть из-за недопустимых параметров командной строки.

ОКРУЖЕНИЕ

COLUMNS

Если задан -t, pod2text возьмёт текущую ширину экрана из этой переменной окружения, если она доступна. Она переопределяет информацию о ширине терминала в TERMCAP.

TERMCAP

Если задан -t, pod2text, если это возможно, использует содержимое этой переменной среды для определения правильных управляющих последовательностей для вашего текущего устройства терминала.

АВТОР

Russ Allbery <rra@cpan.org>.

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

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

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

СМОТРИ ТАКЖЕ

Pod::Text, Pod::Text::Color, Pod::Text::Overstrike, Pod::Text::Termcap, Pod::Simple, perlpod(1)

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