Scroll to navigation

LEXGROG(1) Утилиты просмотра справочных страниц LEXGROG(1)

НАЗВАНИЕ

lexgrog - анализирует заголовочную информацию справочных страниц

СИНТАКСИС

lexgrog [-m|-c] [-dfw?V] [-E кодировка] файл ...

ОПИСАНИЕ

lexgrog — это реализация традиционной “groff guess” утилиты с помощью lex. Она читает список файлов из командной строки, которые являются файлами исходников справочных страниц или уже отформированными (“cat”) страницами, и показывает их названия и описания, используемые apropos и whatis, список предварительных фильтров обработки, требуемый man страницей перед тем как она будет передана nroff или troff, или обеим программам.

Если входные данные неправильно отформатированы, lexgrog выведет “parse failed”; это может оказаться полезным для внешних программ, которым нужно проверять правильность написания man страниц. Если в качестве одного из имён файлов lexgrog передан символ “-”, то данные будут читаться из стандартного входного потока; если любой входной файл сжат, то будет автоматически читаться его расжатая версия.

ПАРАМЕТРЫ

Показывать отладочную информацию.
Анализировать входные данные как файлы исходников справочных страниц. Является действием по умолчанию, если не указан параметр --man или --cat.
Анализировать входные данные как уже отформатированные справочные страницы (“cat страницы”). --man и --cat не могут указываться одновременно.
Показать название и описание из заголовка справочной страницы, используемого apropos и whatis. Является действием по умолчанию, если не указан параметр --whatis или --filters.
Показать список фильтров, необходимых для предварительной обработки справочной страницы перед форматированием с помощью nroff или troff.
Использовать кодировку вместо предполагаемой кодировки символов страницы.
-?, --help
Показать справочное сообщение и закончить работу.
Показать короткое сообщение об использовании и завершить работу.
Показать информацию о версии.

КОД ВЫХОДА

0
Успешное выполнение программы.
1
Ошибка использования.
2
lexgrog не удалось разобрать один или более входных файлов.

ПРИМЕРЫ


$ lexgrog man.1
man.1: "man - an interface to the system reference manuals"
$ lexgrog -fw man.1
man.1 (t): "man - an interface to the system reference manuals"
$ lexgrog -c whatis.cat1
whatis.cat1: "whatis - display manual page descriptions"
$ lexgrog broken.1
broken.1: parse failed

ЧТО АНАЛИЗИРУЕТСЯ

mandb (использует тот же код, что и lexgrog) анализирует раздел NAME (НАЗВАНИЕ), расположенный в самом начале каждой справочной страницы, в поиске названий и описаний возможностей. Хотя анализатор допускает различные вариации и понимает много различных форматов, которые сложились за время использования, иногда он не может извлечь требуемую информацию.

При использовании традиционных наборов макросов man, правильно оформленный раздел NAME выглядит так:

.SH NAME
foo \- программа, выполняющая что-то

Некоторые справочные пейджеры требуют ‘\-’ точно как показано; mandb более терпим, но для совместимости с другими системами всё же лучше оставлять символ обратной косой черты.

Слева от черты могут быть несколько названий, разделённых через запятую. Названия с пробелами будут игнорироваться во избежании необычного поведения для определённо плохо оформленных разделов NAME. У текста справа нет специального формата, и он может располагаться на нескольких строках. Если в одной справочной странице содержатся несколько свойств с различными описаниями, то используется следующая форма:

.SH NAME
foo, bar \- программы, выполняющие что-то
.br
baz \- программа ничего не делающая

(Вместо макроса разрыва .br может использоваться макрос, начинающий новый параграф, типа .PP.)

Если используется BSD-производный набор макросов mdoc, то правильно оформленный раздел NAME выглядит так:

.Sh NAME
.Nm foo
.Nd программа, выполняющая что-то

Есть несколько распространённых причин, по которым анализ может завершаться неудачно. Иногда авторы справочных страниц заменяют ‘.SH NAME’ на ‘.SH MYPROGRAM’, и поэтому mandb не может найти раздел, из которого нужно извлекать информацию. Иногда авторы включают раздел NAME, но размещают его в свободной форме, а не как положено ‘название \- описание’. Однако любой синтаксис, приведённый выше, будет понят.

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

apropos(1), man(1), whatis(1), mandb(8)

ЗАМЕЧАНИЯ

lexgrog пытается проанализировать файлы, содержащие запросы .so, но сможет это сделать, если только файлы правильно установлены в иерархии справочных страниц.

АВТОР

Авторы кода, используемого lexgrog для сканирования справочных страниц:

Wilf. (G.Wilford@ee.surrey.ac.uk).
Fabrizio Polacco (fpolacco@debian.org).
Colin Watson (cjwatson@debian.org).

Колин Ватсон (Colin Watson) написал текущий вариант для интерфейса командной строки, а также данную справочную страницу.

ОШИБКИ

https://gitlab.com/cjwatson/man-db/-/issues
https://savannah.nongnu.org/bugs/?group=man-db

2022-03-17 2.10.2