pod2text

СОДЕРЖАНИЕ

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

ИМЯ

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

СИНТАКСИС

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

pod2text -h

ОПИСАНИЕ

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

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

По умолчанию кодировка вывода совпадает с кодировкой входного файла или UTF-8, если кодировка входного файла не задана (кроме систем EBCDIC). Смотрите параметр -e для явного задания кодировки вывода и "Encoding" в Pod::Text для более подробной информации.

ПАРАМЕТРЫ

Каждый параметр сопровождается версией подпрограммы podlators, в которой он был добавлен, и его текущим значением.

-a, --alt

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

--code

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

-c, --color

[1.00] Форматирует вывод с помощью ANSI цветных последовательностей. Использование этого параметра требует установки Term::ANSIColor на вашей системе.

-e encoding, --encoding=encoding

[5.00] Указывает кодировку вывода. encoding должен быть кодировкой, распознаваемой модулем Encode (см. Encode::Supported). Если вывод содержит символы, которые не могут быть представлены в этой кодировке, это ошибка, которая будет сообщена в соответствии с настройками параметра errors. Если обработка ошибок отличается от die, непредставимый символ будет заменён замещающим символом Encode (обычно ?).

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

--errors=style

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

По умолчанию die.

--guesswork=rule[,rule...]

[5.01] По умолчанию pod2text применяет некоторые правила форматирования по умолчанию, основанные на догадках и регулярных выражениях, которые предназначены для упрощения написания документации Perl и требуют меньше явного разметки. Эти правила могут не всегда быть уместными, особенно для документации, которая не о Perl. Этот параметр позволяет отключить все или некоторые из них.

Специальное правило all включает все догадки. Это также значение по умолчанию по соображениям обратной совместимости. Специальное правило none отключает все догадки. В противном случае значение этого параметра должно быть список слов, разделённых запятыми, из следующих:

quoting

Если никаких догадок не включено, любой текст в C<> окружён двойными кавычками в nroff (терминале), если содержание не цитируется. Когда эта догадка включена, кавычки также подавляются для переменных Perl, имён функций, вызовов функций, чисел и шестнадцатеричных констант.

Любое неизвестное имя догадки будет проигнорировано (для потенциальной будущей совместимости), поэтому будьте внимательны к написанию.

-i indent, --indent=indent

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

-h, --help

[1.00] Выводит справку по использованию и завершает работу.

-l, --loose

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

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

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

--nourls

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

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

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

foo <http://example.com/>

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

-o, --overstrike

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

-q quotes, --quotes=quotes

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

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

-s, --sentence

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

--stderr

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

-t, --termcap

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

-u, --utf8

[2.2.0] Устанавливает кодировку вывода в UTF-8. Это эквивалентно --encoding=UTF-8 и поддерживается для обратной совместимости.

-w, --width=width, -width

[1.00] Колонка, на которой обрезать текст справа. По умолчанию 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, 2022 Russ Allbery <rra@cpan.org>

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

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

Encode::Supported, 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.