Arch manual pages

LEXGROG(1) Hulpprogramma's paginaopmaker LEXGROG(1)

lexgrog - hoofdinginformatie in manpagina's ontleden

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

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.

-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.

0
Programma correct uitgevoerd.
1
Gebruiksfout.
2
lexgrog kon een of meer van de invoerpagina's niet ontleden.

  $ 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

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.

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

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.

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.

2019-10-23 2.9.0