LEXGROG(1) Værktøjer til manualsider LEXGROG(1)

lexgrog - fortolk hovedfilsinformation i manualsider

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

lexgrog er en implementering af det traditionelle “groff guess”-redskab i lex. Det læser listen med filer på kommandolinjen som enten manualsidekildefiler eller præformaterede “cat”-sider, og viser deres navn og beskrivelse som brugt af apropos og whatis, listen med forhåndsbehandlede filtre krævet af manualsiden før den sendes til nroff eller troff, eller begge.

Hvis inddata er dårligt formateret vil lexgrog vise “parse failed”; dette kan være nyttigt for eksterne programmer, som skal kontrollere manualsider for korrekthed. Hvis en af lexgrog's inddatafiler er “-”, så vil det læse fra standardinddata; hvis nogle af inddatafilerne er komprimeret, så vil en udpakket version blive læst automatisk.

Vis fejlsøgningsinformation.
Fortolk inddata som kildefiler for manualsider. Dette er standarden hvis hverken --man eller --cat er angivet.
Fortolk inddata som præformaterede manualsider (“cat pages”). --man og --cat kan ikke angives simultant.
Vis navnet og beskrivelsen fra manualsidens teksthoved, som brugt af apropos og whatis. Dette er standarden hvis hverken --whatis eller --filters er angivet.
Vis listen med filtre krævet for at forbehandle manualsiden før formatering med nroff eller troff.
Overstyr det gættede tegnsæt for siden til encoding.
-?, --help
Vis en hjælpebesked og afslut.
Vis en kort hjælpebesked og afslut.
Vis versionsinformation.

0
Programkørsel endt uden fejl.
1
Fejl i anvendelse.
2
lexgrog mislykkedes i at fortolke en eller flere af dets inddatafiler.

  $ 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 (som bruger den samme kode som lexgrog) fortolker afsnittet NAME øverst for hver manualside på udkig efter navne og beskrivelser for funktionerne dokumenteret i hver. Selvom fortolkeren er ret så tolerant, da den skal håndtere et antal forskellige formularer, som historik er blevet anvendt, så kan den fejle i sit udtræk af den krævede information.

Når det traditionelle makrosæt man anvendes, så ser et korrekt NAME-afsnit cirka sådan her ud:

.SH NAME
foo \- program to do something

Nogle manualsøgere kræver at ‘\-’ to er præcis som vist; mandb er mere tolerant, men af kompatibilitetsårsager er det alligevel en god ide at bevare skråstregen.

På den venstre side, kan der være flere navne, adskilt af kommaer. Navne indeholdende mellemrum vil blive ignoreret for at undgå patologisk opførsel på bestemet forkert udformet NAME-sektioner. Teksten på den højre side er fri, og kan spredes over flere linjer. Hvis flere funktioner med forskellige beskrivelser bliver dokumenteret på den samme manualside, så bruges den følgende form:

.SH NAME
foo, bar \- programs to do something
.br
baz \- program to do nothing

(A macro which starts a new paragraph, like .PP, may be used instead of the break macro .br.)

Når der bruges det BSD-afledte mdoc-makrosæt, så ligner en korrekt NAME-sektion noget lignende dette:

.Sh NAME
.Nm foo
.Nd program to do something

Der er flere gængse årsager til at whatis-fortolkning mislykkes. Nogle gange erstatter forfattere af manualsider ‘.SH NAME’ med ‘.SH MYPROGRAM’, og så kan mandb ikke finde afsnittet hvorfra informationen, den har brug for, skal udtrækkes. Undertiden inkluderer forfatteren et NAVNE-afsnit, men placerer fri-form tekst der frem for ‘name \- beskrivelse’. Dog bør enhver syntaks der ligner ovenstående blive accepteret.

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

lexgrog forsøger at fortolke filer der indeholder .so-forespørgsler, men vil kun kunne gøre det korrekt hvis filerne er korrekt installeret i et manualsidehierarki.

Koden brugt af lexgrog til at skanne manualsider blev skrevet af:

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

Colin Watson skrev den aktuelle inkarnation af kommandolinjebrugerfladen, samt denne manualside.

https://gitlab.com/man-db/man-db/-/issues
https://savannah.nongnu.org/bugs/?group=man-db

2024-08-29 2.13.0