НАЗВАНИЕ¶
lexgrog -
анализирует
заголовочную
информацию
справочных
страниц
СИНТАКСИС¶
lexgrog [
-m|
-c] [
-fhwV] [
-E
кодировка]
файл ...
ОПИСАНИЕ¶
lexgrog -- это
реализация
традиционной
“groff guess” утилиты
с помощью
lex.
Она читает
список
файлов из
командной
строки,
которые
являются
файлами
исходников
справочных
страниц или
уже
отформированными
(“cat”)
страницами,
и показывает
их названия
и описания,
используемые
apropos и
whatis,
список
предварительных
фильтров
обработки,
требуемый man
страницей
перед тем
как она
будет
передана
nroff
или
troff, или
обеим
программам.
Если входные
данные
неправильно
отформатированы,
lexgrog выведет “parse
failed”; это может
оказаться
полезным для
внешних
программ,
которым
нужно
проверять
правильность
написания man
страниц.
Если в
качестве
одного из
имён файлов
lexgrog передан
символ “-”, то
данные будут
читаться из
стандартного
входного
потока; если
любой
входной файл
сжат, то
будет
автоматически
читаться его
расжатая
версия.
ПАРАМЕТРЫ¶
- -m, --man
- Анализировать
входные
данные как
файлы
исходников
справочных
страниц.
Является
действием
по
умолчанию,
если не
указан
параметр --man
или --cat.
- -c, --cat
- Анализировать
входные
данные как
уже
отформатированные
справочные
страницы (“cat
страницы”).
--man и --cat не
могут
указываться
одновременно.
- -w, --whatis
- Показать
название и
описание из
заголовка
справочной
страницы,
используемого
apropos и whatis.
Является
действием
по
умолчанию,
если не
указан
параметр --whatis
или --filters.
- -f, --filters
- Показать
список
фильтров,
необходимых
для
предварительной
обработки
справочной
страницы
перед
форматированием
с помощью nroff
или troff.
- -E
кодировка,
--encoding
кодировка
- Использовать
кодировку
вместо
предполагаемой
кодировки
символов
страницы.
- -h, --help
- Показать
справочное
сообщение и
закончить
работу.
- -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) написал
текущий
вариант для
интерфейса
командной
строки, а
также данную
справочную
страницу.