lexgrog - tolka rubrikhuvud i manualsidor
lexgrog [
-m|
-c] [
-dfw?V] [
-E kodning]
fil ...
lexgrog är en implementation av det traditionella verktyget
“groff guess” i
lex. Det läser listan av filer
på dess kommandorad antingen som källkodsfiler till manualsidor
eller förformaterade “cat” sidor, och visar deras namn
och beskrivning så som de används av
apropos och
whatis, som en lista av preprocessorfilter som krävs av
manualsidan innan den skickas vidare till
nroff eller
troff,
eller båda delar.
Om inmatningen är dåligt formaterad kommer
lexgrog att
skriva ut “tolkning misslyckades”; detta kan vara
användbart för externa program som behöver kontrollera
manualsidors korrekthet. Om en av
lexgrog:s inmatningsfiler är
“-” så kommer det att läsa från standard
in; om någon inmatningsfil är komprimerad kommer en
dekomprimerad version automatiskt att läsas in.
-
-d, --debug
- Skriver ut felsökningsinformation.
-
-m, --man
- Tolka inmatning som källkodsfiler till manualsidor.
Detta är standard om varken --man eller --cat
anges.
-
-c, --cat
- Tolka inmatning som förformaterade manualsidor
(“cat-sidor”). --man och --cat får inte
anges samtidigt.
-
-w, --whatis
- Visa namnet och beskrivningen från manualsidans
rubrikhuvud så som de används av apropos och
whatis. Detta är standard om varken --whatis eller
--filters anges.
-
-f, --filters
- Visa listan över filter som behövs för
att förformatera manualsidan innan den formateras med nroff
eller troff.
-
-E kodning, --encoding
kodning
- Åsidosätt den gissade
teckenuppsättningen för sidan och använd
kodning.
-
-?, --help
- Skriv ut ett hjälpmeddelande och avsluta.
- --usage
- Skriv ut ett kort användningsmeddelande och
avsluta.
-
-V, --version
- Visa versionsinformation.
- 0
- Framgångsrik programexekvering.
- 1
- Användningsfel.
- 2
-
lexgrog misslyckades med att tolka en eller flera av
dess inmatningsfiler.
$ lexgrog man.1
man.1: "man - ett gränssnitt för systemreferensmanualer"
$ lexgrog -fw man.1
man.1 (t): "man - ett gränssnitt för systemreferensmanualer"
$ lexgrog -c whatis.cat1
whatis.cat1: "whatis - visa beskrivningar för manualsidor"
$ lexgrog broken.1
broken.1: tolkning misslyckades
mandb (som använder samma kod som
lexgrog) tolkar
NAMN-avsnittet längst upp på varje manualsida och letar
efter namn och beskrivningar för de funktioner som dokumenteras i varje
sida. Även om tolken är tämligen tolerant, då den
varit tvungen att klara av ett antal olika format som använts
historiskt, kan den ibland misslyckas med att extrahera den begärda
informationen.
När den traditionella makrouppsättningen
man används
ser ett
NAMN-avsnitt ut ungefär så här:
.SH NAMN foo \- program som gör någonting
Vissa manualsidor kräver att ‘\-’ anges exakt som visats;
mandb är mer tolerant, men för kompatibilitet med andra
system är det trots detta en bra idé att behålla
bakstrecket.
På vänstersidan kan det finnas flera namn, separerade av komman.
Namn som innehåller blanksteg kommer att ignoreras för att
undvika felaktigt beteende för vissa dåligt namngivna
NAMN-avsnitt. Texten på höger sida är friformstext
och får sträcka sig över flera rader. Om flera funktioner
med olika beskrivningar dokumenteras på samma manualsida ska
därför följande form användas:
.SH NAMN foo, bar \- program som gör någonting .br baz \- program som inte gör någonting
(Ett makro som påbörjar ett nytt stycke, så som .PP, kan
användas istället för avbrytningsmakrot .br.)
När den BSD-baserade makrouppsättningen
mdoc används
ser ett
NAMN-avsnitt ut ungefär så här:
.Sh NAMN .Nm foo .Nd program som för någonting
Det finns flera anledningar till varför whatis-tolkning misslyckas.
Ibland ersätter upphovsmännen till manualsidorna ‘.SH
NAMN’ med ‘.SH MITTPROGRAM’ och så kan inte
mandb hitta avsnittet från vilket informationen det
behöver ska extraheras. Ibland inkluderar upphovsmännen
NAMN-avsnittet, men placerar friformstext där snarare än
‘namn \- beskrivning’. Syntax som är lik
ovanstående bör dock accepteras.
apropos(1),
man(1),
whatis(1),
mandb(8)
lexgrog försöker att tolka filer som innehåller
.so-begäran men kommer endast att lyckas göra det korrekt om
filerna är korrekt installerade i hierarkin av manualsidor.
Koden som används av
lexgrog för att genomsöka
manualsidor skrevs av:
Wilf. ([email protected]).
Fabrizio Polacco ([email protected]).
Colin Watson ([email protected]).
Colin Watson skrev den innevarande inkarnationen av
kommandoradsgränssnittet, såväl som denna manualsida.
https://gitlab.com/man-db/man-db/-/issues
https://savannah.nongnu.org/bugs/?group=man-db