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¶

0

Programma correct uitgevoerd.

1

Gebruiksfout.

2

lexgrog kon een of meer van de invoerpagina's niet ontleden.

VOORBEELDEN¶

  $ lexgrog man.1


  man.1: "man - een interface met de online-handleidingen"


  $ lexgrog -fw man.1


  man.1 (t): "man - een interface met de online-handleidingen"


  $ lexgrog -c whatis.cat1


  whatis.cat1: "whatis - beschrijvingen man-pagina tonen"


  $ lexgrog broken.1


  broken.1: ontleden is mislukt

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 NAAM
foo \- applicatie die iets doet

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 NAAM
foo, bar \- applicaties om iets te doen
.br
baz \- applicatie om niets te doen

(In plaats van de alineascheidingsmacro .br., kan een macro die een nieuwe alinea begint gebruikt worden, zoals .PP.

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

.Sh NAAM
.Nm foo
.Nd applicatie om iets te doen

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@ee.surrey.ac.uk).
Fabrizio Polacco (fpolacco@debian.org).
Colin Watson (cjwatson@debian.org).

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