1LEXGROG(1)                    Manual pager utils                    LEXGROG(1)
2
3
4

NAME

6       lexgrog - parse header information in man pages
7

SYNOPSIS

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

DESCRIPTION

12       lexgrog  is  an implementation of the traditional “groff guess” utility
13       in lex.  It reads the list of files on its command line as  either  man
14       page  source files or preformatted “cat” pages, and displays their name
15       and description as used by apropos and whatis, the list of  preprocess‐
16       ing  filters  required  by the man page before it is passed to nroff or
17       troff, or both.
18
19       If its input is badly formatted, lexgrog  will  print  “parse  failed”;
20       this  may  be useful for external programs that need to check man pages
21       for correctness.  If one of lexgrog's input files is “-”, it will  read
22       from  standard  input;  if any input file is compressed, a decompressed
23       version will be read automatically.
24

OPTIONS

26       -d, --debug
27              Print debugging information.
28
29       -m, --man
30              Parse input as man page source files.  This is  the  default  if
31              neither --man nor --cat is given.
32
33       -c, --cat
34              Parse  input as preformatted man pages (“cat pages”).  --man and
35              --cat may not be given simultaneously.
36
37       -w, --whatis
38              Display the name and description from the man page's header,  as
39              used  by  apropos  and  whatis.   This is the default if neither
40              --whatis nor --filters is given.
41
42       -f, --filters
43              Display the list of filters needed to preprocess  the  man  page
44              before formatting with nroff or troff.
45
46       -E encoding, --encoding encoding
47              Override the guessed character set for the page to encoding.
48
49       -?, --help
50              Print a help message and exit.
51
52       --usage
53              Print a short usage message and exit.
54
55       -V, --version
56              Display version information.
57

EXIT STATUS

59       0      Successful program execution.
60
61       1      Usage error.
62
63       2      lexgrog failed to parse one or more of its input files.
64

EXAMPLES

66         $ lexgrog man.1
67         man.1: "man - an interface to the system reference manuals"
68         $ lexgrog -fw man.1
69         man.1 (t): "man - an interface to the system reference manuals"
70         $ lexgrog -c whatis.cat1
71         whatis.cat1: "whatis - display manual page descriptions"
72         $ lexgrog broken.1
73         broken.1: parse failed
74

WHATIS PARSING

76       mandb  (which uses the same code as lexgrog) parses the NAME section at
77       the top of each manual page looking for names and descriptions  of  the
78       features documented in each.  While the parser is quite tolerant, as it
79       has to cope with a number of different  forms  that  have  historically
80       been used, it may sometimes fail to extract the required information.
81
82       When  using the traditional man macro set, a correct NAME section looks
83       something like this:
84
85              .SH NAME
86              foo \- program to do something
87
88       Some manual pagers require the ‘\-’ to be exactly as  shown;  mandb  is
89       more tolerant, but for compatibility with other systems it is neverthe‐
90       less a good idea to retain the backslash.
91
92       On the left-hand side, there may be several names, separated by commas.
93       Names  containing  whitespace will be ignored to avoid pathological be‐
94       haviour on certain ill-formed NAME sections.  The text  on  the  right-
95       hand side is free-form, and may be spread over multiple lines.  If sev‐
96       eral features with different descriptions are being documented  in  the
97       same manual page, the following form is therefore used:
98
99              .SH NAME
100              foo, bar \- programs to do something
101              .br
102              baz \- program to do nothing
103
104       (A macro which starts a new paragraph, like .PP, may be used instead of
105       the break macro .br.)
106
107       When using the BSD-derived mdoc macro set, a correct NAME section looks
108       something like this:
109
110              .Sh NAME
111              .Nm foo
112              .Nd program to do something
113
114       There  are  several common reasons why whatis parsing fails.  Sometimes
115       authors of manual pages replace ‘.SH NAME’ with  ‘.SH  MYPROGRAM’,  and
116       then  mandb  cannot find the section from which to extract the informa‐
117       tion it needs.  Sometimes authors include a  NAME  section,  but  place
118       free-form  text  there rather than ‘name \- description’.  However, any
119       syntax resembling the above should be accepted.
120

SEE ALSO

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

NOTES

125       lexgrog attempts to parse files containing .so requests, but will  only
126       be  able  to  do  so correctly if the files are properly installed in a
127       manual page hierarchy.
128

AUTHOR

130       The code used by lexgrog to scan man pages was written by:
131
132       Wilf. (G.Wilford@ee.surrey.ac.uk).
133       Fabrizio Polacco (fpolacco@debian.org).
134       Colin Watson (cjwatson@debian.org).
135
136       Colin Watson wrote the current incarnation of the  command-line  front-
137       end, as well as this man page.
138
139
140
1412.9.0                             2019-10-23                        LEXGROG(1)
Impressum