Arch manual pages

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.

-d, --debug
Vis fejlsøgningsinformation.
-m, --man
Fortolk inddata som kildefiler for manualsider. Dette er standarden hvis hverken --man eller --cat er angivet.
-c, --cat
Fortolk inddata som præformaterede manualsider (“cat pages”). --man og --cat kan ikke angives simultant.
-w, --whatis
Vis navnet og beskrivelsen fra manualsidens teksthoved, som brugt af apropos og whatis. Dette er standarden hvis hverken --whatis eller --filters er angivet.
-f, --filters
Vis listen med filtre krævet for at forbehandle manualsiden før formatering med nroff eller troff.
-E kodning, --encoding kodning
Overstyr det gættede tegnsæt for siden til encoding.
-?, --help
Vis en hjælpebesked og afslut.
--usage
Vis en kort hjælpebesked og afslut.
-V, --version
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 on-line reference manuals"
  $ lexgrog -fw man.1
  man.1 (t): "man - an interface to the on-line 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 til udførsel

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 \- programmer til at gøre noget
.br
baz \- program til ikke at gøre noget

(En makro som starter et nyt afsnit, såsom .PP, kan bruges i stedet for break-makroen .br.)

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

.Sh NAVN
.Nm foo
.Nd program der skal udføre noget

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.

2019-01-05 2.8.5