Manpages

NAAM

lexgrog - hoofdinginformatie in manpagina’s ontleden

SAMENVATTING

lexgrog [-m|-c] [-dfw?V] [-E encoding] file ...

BESCHRIJVING

lexgrog is een implementatie van het traditionele “groff guess”-hulpprogramma in lex. Het leest de bestandslijst in de opdrachtregel als man-paginabronbestanden of als gestructureerde “cat”-pagina’s, en toont hun naam en beschrijving zoals deze in apropos en watis gebruikt worden.o De lijst bevat preprocessingfilters die vereist zijn door de man-pagina, voor het doorgegeven wordt aan nroff of troff of aan beide.

Als de invoer slecht gestructureerd is, dan zal lexgrog “parse failed” tonen; dit kan nuttig zijn voor externe programma’s die de man-pagina’s op juistheid controleren. Wanneer één van lexgrog’s invoerbestanden (lq-” is, dan wordt uit de standaardinvoer gelezen; als enig invoerbestand gecomprimeerd is, dan zal een gedecomprimeerde versie automatisch worden ingelezen.

OPTIES

-d, --debug

Foutinformatie tonen.

-m, --man

Invoer als man-paginabronbestanden ontleden. Dit is de standaard als --man noch --cat is opgegeven.

-c, --cat

Invoer als voorgestructureerde man-pagina’s ontleden (“cat pages”). --man en --cat hoeven niet gelijktijdig opgegeven te worden.

-w, --whatis

De naam en beschrijving van de hoofding van man-pagina’s tonen zoals deze worden gebruikt door apropos and watis. Dit is de standaard als --whatis noch --filters opgegeven is.

-f, --filters

De lijst met filters tonen die nodig zijn om de man-pagina voor te bewerken voordat nroff of troff deze opmaakt.

-E codering, --encoding codering

De gekozen karakterset voor de pagina forceren naar codering.

-?, --help

Een hulptekst tonen en stoppen.

--usage

Print a short usage message and exit.

-V, --version

Versieinformatie tonen.

STOPSTATUS

VOORBEELDEN

$ 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

WATIS-ONTLEDING

mandb (die dezelfde broncode als lexgrog gebruikt) ontleedt het NAAM-deel bovenaan iedere handleidingspagina, zoekend naar namen en beschrijvingen van de daarin gedocumenteerde functionaliteiten. Hoewel de parser vrij soepel is omdat het rekening moet houden met een aantal historisch gegroeide vormen, kan het soms falen bij het ophalen van de vereiste informatie.

Bij gebruik van de traditionele man-macroverzameling, ziet een correcte NAAM-sectie er ongeveer als volgt uit:

.SH NAME
foo \- program to do something

Sommige opmakers van man-pagina’s vereisen de ’\-’ precies zoals getoond; mandb is wat soepeler, maar vanwege compatibiliteit met andere systemen, is het toch een goed idee om de backslash te behouden.

Aan de linkerzijde zullen verschillende namen staan, gescheiden door komma’s. Namen die spaties bevatten worden genegeerd om pathologisch gedrag bij sommige, slecht-opgemaakte NAAM-secties te voorkomen. De tekst aan de rechterzijde is vrij en kan verdeeld worden over meerdere regels. Als meerdere functionaliteiten met verschillende beschrijvingen in dezelfde man-pagina’s zijn gedocumenteerd, wordt hiervoor de volgende vorm gebruikt:

.SH NAME
foo, bar \- programs to do something
.br
baz \- program to do nothing

(A macro which starts a new paragraph, like .PP, may be used instead of the break macro .br.)

Bij het gebruik van een mdoc-macroverzameling die is afgeleid van het BSD, ziet een correcte NAAM-sectie er als volgt uit:

.Sh NAME
.Nm foo
.Nd program to do something

Er zijn meerdere, veelvoorkomende redenen waarom ontleden van watis mislukt. Soms vervangen de auteurs van man-pagina’s ’.SH NAME’ door ’.SH MYPROGRAM’, waardoor mandb het deel niet kan vinden waaruit de benodigde informatie moet worden gehaald. Soms voegen auteurs wel de NAAM-sectie toe, maar gebruiken daarbij vrije tekst in plaats van ’name \- description’. Echter, iedere syntax die met het bovenstaande overeenkomt moet geaccepteerd worden.

ZIE OOK

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

OPMERKINGEN

lexgrog poogt alleen bestanden met .so-verzoeken te ontleden, maar die kan dat alleen doen als de bestanden correct geïnstalleerd zijn in een man-paginastructuur.

AUTEUR

De broncode die gebruikt wordt door lexgrog om man-pagina’s te scannen is geschreven door:

Wilf. (G.Wilford [AT] ee.uk).
Fabrizio Polacco (fpolacco [AT] debian.org).
Colin Watson (cjwatson [AT] debian.org).

Colin Watson schreef de huidige reïncarnatie van de opdrachtregel-frontend, en ook deze man-pagina.

BUGS

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