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 цветовые последовательности для форматирования текста.

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

ПАРАМЕТРЫ

-a, --alt

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

--code

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

-c, --color

Форматирование вывода с помощью ANSI цветовых последовательностей. Для использования этого параметра необходимо, чтобы 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

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

--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-2018 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.