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.