NAMN¶

lexgrog - tolka rubrikhuvud i manualsidor

SYNOPSIS¶

lexgrog [-m|-c] [-dfw?V] [-E kodning] fil ...

BESKRIVNING¶

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.

FLAGGOR¶

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

SLUTSTATUS¶

0

Framgångsrik programexekvering.

1

Användningsfel.

2

lexgrog misslyckades med att tolka en eller flera av dess inmatningsfiler.

EXEMPEL¶

  $ lexgrog man.1


  man.1: "man - ett gränssnitt för direktreferensmanualer"


  $ lexgrog -fw man.1


  man.1 (t): "man - ett gränssnitt för direktreferensmanualer"


  $ lexgrog -c whatis.cat1


  whatis.cat1: "whatis - visa beskrivningar för manualsidor"


  $ lexgrog broken.1


  broken.1: tolkning misslyckades

WHATIS-TOLKNING¶

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.

SE VIDARE¶

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

NOTERINGAR¶

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.

UPPHOVSMAN¶

Koden som används av lexgrog för att genomsöka manualsidor skrevs av:

Wilf. (G.Wilford@ee.surrey.ac.uk).
Fabrizio Polacco (fpolacco@debian.org).
Colin Watson (cjwatson@debian.org).

Colin Watson skrev den innevarande inkarnationen av kommandorads gränssnittet, såväl som denna manualsida.