НАЗВАНИЕ¶
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
- Ошибка
использования.
- 2
- lexgrog не
удалось
разобрать
один или
более
входных
файлов.
ПРИМЕРЫ¶
$ lexgrog man.1
man.1: "man - an interface to the on-line reference manuals"
$ lexgrog -fw man.1
man.1 (t): "man - an interface to the on-line 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)
написал
текущий
вариант
для
интерфейса
командной
строки, а
также
данную
справочную
страницу.