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.