ІМʼЯ

lexgrog - аналізувати інформацію заголовку в сторінках довідки

СИНОПСИС

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

ОПИС

lexgrog - це реалізація традиційної утиліти «groff guess» в lex. Вона читає список файлів, переданих їй як аргументи командного рядка, як джерело сторінок man або вже відформатовані «cat» сторінки, і показує їх назву та опис, використовуючи apropos та whatis, список попередніх фільтрів, необхідних для сторінки man перед тим, як вона буде передана до nroff або troff, або обох.

Якщо його вхідні дані погано сформовані, lexgrog над «parse failed». Це може бути корисним для зовнішніх програм, які повинні перевіряти сторінки man на правильність. Якщо один з вхідних файлів lexgrog є «-», він прочитає дані зі стандартного вводу; якщо будь-який вхідний файл стиснутий, буде автоматично прочитана розпакована версія.

ПАРАМЕТРИ

-d, --debug: Вивести інформацію для налагодження.
-m, --man: Аналізувати вхідні дані як джерело сторінок man. Це значення за замовчуванням, якщо не вказано ні --man, ні --cat.
-c, --cat: Аналізувати вхідні дані як форматовані сторінки довідки («сторінки cat»). --man та --cat не можуть бути задані одночасно.
-w, --whatis: Показати назву та опис із заголовка сторінки man, як використовується у apropos і whatis. Це значення за замовчуванням, якщо не вказано ні --whatis, ні --filters.
-f, --filters: Показати список фільтрів, необхідних для попередньої обробки сторінки man перед форматуванням за допомогою nroff або troff.
-E кодування, --encoding кодування: Перевизначити вгадану кодову сторінку для сторінки на кодування.
-?, --help: Надрукувати повідомлення довідки та вийти.
--usage: Надрукувати коротке повідомлення про використання та вийти.
-V, --version: Показати інформацію про версію.

СТАТУС ВИХОДУ

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

ПРИКЛАДИ

  $ lexgrog man.1
  man.1: "man - інтерфейс до системних довідкових керівництв"
  $ lexgrog -fw man.1
  man.1 (t): "man - інтерфейс до системних довідкових керівництв"
  $ lexgrog -c whatis.cat1
  whatis.cat1: "whatis - показувати описи сторінок довідки"
  $ lexgrog broken.1
  broken.1: синтаксичний аналіз не вдався

РОЗБІР WHATIS

mandb (яка використовує той самий код, що і lexgrog) аналізує розділ NAME у верхній частині кожної сторінки довідника, шукаючи назви та описи функцій, які документуються в кожному. Хоча аналізатор досить толерантний, оскільки він має впоратися з багатьма різними формами, що історично використовувалися, йому іноді може не вдаватися видобути необхідну інформацію.

При використанні традиційного набору макросів man, правильний розділ NAME виглядає приблизно так:

.SH NAME
foo \- програма для виконання певних дій

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

Зліва можуть бути вказано кілька імен, розділених комами. Імена, що містять пробіли, будуть ігноруватися, щоб уникнути патологічної поведінки в певних неправильно сформованих секціях NAME. Текст праворуч є довільним та може розподілятися на кілька рядків. Якщо в одній сторінці керівництва описується кілька функцій з різними описами, то використовується наступна форма:

.SH NAME
foo, bar \- програми для виконання певних дій
.br
baz \- програма, яка нічого не робить

(Макрос, який починає новий абзац, на кшталт .PP, може бути використаний замість макросу перенесення рядка .br.)

При використанні набору макросів mdoc, похідних від BSD, правильний розділ NAME виглядає приблизно так:

.Sh NAME
.Nm foo
.Nd програма для виконання певних дій

Існує кілька поширених причин, чому аналіз whatis не вдається. Іноді автори сторінок довідки замінюють ‘.SH NAME’ на ‘.SH MYPROGRAM’, і тоді mandb не може знайти розділ, з якого потрібно витягнути необхідну інформацію. Іноді автори включають розділ NAME, але розміщують там вільний текст замість ‘name \- опису’. Проте, будь-яка синтаксична конструкція, що нагадує вищезазначене, повинна бути прийнятною.

ДИВ. ТАКОЖ

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

ПРИМІТКИ

lexgrog намагається аналізувати файли, які містять запити .so, але зможе це робити правильно тільки тоді, коли ці файли будуть правильно встановлені у ієрархії сторінок довідки.

АВТОР

Код, який використовується lexgrog для сканування сторінок man, написаний:

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

Колін Вотсон написав поточну версію інтерфейсу командного рядка, а також цю сторінку довідки.

ПОМИЛКИ

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