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 воспользуется содержимым этой переменной среды, если она доступна, для определения правильных последовательностей форматирования для вашего текущего типа терминала.

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

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

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

АВТОР

Russ Allbery <rra@cpan.org>.

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

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

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