НАЗВАНИЕ

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

СИНТАКСИС

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

ОПИСАНИЕ

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

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

ПАРАМЕТРЫ

-d, --debug
Показывать отладочную информацию.

-m, --man
Анализировать входные данные как файлы исходников справочных страниц.
Является действием по умолчанию, если не указан параметр --man или --cat.

-c, --cat
Анализировать входные данные как уже отформатированные справочные страницы
(“cat страницы”). --man и --cat не могут указываться одновременно.

-w, --whatis
Показать название и описание из заголовка справочной страницы,
используемого apropos и whatis. Является действием по умолчанию, если не
указан параметр --whatis или --filters.

-f, --filters
Показать список фильтров, необходимых для предварительной обработки
справочной страницы перед форматированием с помощью nroff или troff.

-E кодировка, --encoding кодировка
Использовать кодировку вместо предполагаемой кодировки символов страницы.

-?, --help
Показать справочное сообщение и закончить работу.

--usage
Показать короткое сообщение об использовании и завершить работу.

-V, --version
Показать информацию о версии.

КОД ВЫХОДА

0 Успешное выполнение программы.

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