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

Предполагает, что каждая строка заканчивается двумя пробелами, и пытается сохранить это расстояние. Без этого параметра все последовательные пробелы в не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, обрабатываемом pod2text, есть синтаксические ошибки и стиль обработки ошибок установлен по умолчанию 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.