Penguin
Recent Changes
Annotated edit history of lexgrog(1) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 lexgrog
2 !!!lexgrog
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 OPTIONS
7 EXIT STATUS
8 EXAMPLES
9 WHATIS PARSING
10 SEE ALSO
11 NOTES
12 AUTHOR
13 ----
14 !!NAME
15
16
17 lexgrog - parse header information in man pages
18 !!SYNOPSIS
19
20
21 __lexgrog__ [[__-m__|__-c__] [[__-fhwV__]
22 ''file'' ...
23 !!DESCRIPTION
24
25
26 __lexgrog__ is an implementation of the traditional
27 ``groff guess'' utility in __lex__. It reads the list of
28 files on its command line as either man page source files or
29 preformatted ``cat'' pages, and displays their name and
30 description as used by __apropos__ and __whatis__, the
31 list of preprocessing filters required by the man page
32 before it is passed to __nroff__ or __troff__, or
33 both.
34
35
36 If its input is badly formatted, __lexgrog__ will print
37 ``parse failed''; this may be useful for external programs
38 that need to check man pages for correctness. If one of
39 __lexgrog__'s input files is ``-'', it will read from
40 standard input; if any input file is compressed, a
41 decompressed version will be read
42 automatically.
43 !!OPTIONS
44
45
46 __-m, --man__
47
48
49 Parse input as man page source files. This is the default if
50 neither __--man__ nor __--cat__ is given.
51
52
53 __-c, --cat__
54
55
56 Parse input as preformatted man pages (``cat pages'').
57 __--man__ and __--cat__ may not be given
58 simultaneously.
59
60
61 __-w, --whatis__
62
63
64 Display the name and description from the man page's header,
65 as used by __apropos__ and __whatis__. This is the
66 default if neither __--whatis__ nor __--filters__ is
67 given.
68
69
70 __-f, --filters__
71
72
73 Display the list of filters needed to preprocess the man
74 page before formatting with __nroff__ or
75 __troff__.
76
77
78 __-h, --help__
79
80
81 Print a help message and exit.
82
83
84 __-V, --version__
85
86
87 Display version and author information.
88 !!EXIT STATUS
89
90
91 __0__
92
93
94 Successful program execution.
95
96
97 __1__
98
99
100 Usage error.
101
102
103 __2__
104
105
106 __lexgrog__ failed to parse one or more of its input
107 files.
108 !!EXAMPLES
109
110
111 $ lexgrog man.1
112 man.1:
113 !!WHATIS PARSING
114
115
116 __mandb__ (which uses the same code as __lexgrog__)
117 parses the __NAME__ section at the top of each manual
118 page looking for names and descriptions of the features
119 documented in each. While the parser is quite tolerant, as
120 it has to cope with a number of different forms that have
121 historically been used, it may sometimes fail to extract the
122 required information.
123
124
125 A correct __NAME__ section looks something like
126 this:
127
128
129 .SH NAME
130 foo - program to do something
131
132
133 Some manual pagers require the `-' to be exactly as shown;
134 __mandb__ is more tolerant, but for compatibility with
135 other systems it is nevertheless a good idea to retain the
136 backslash.
137
138
139 On the left-hand side, there may be several names, separated
140 by commas. The text on the right-hand side is free-form, and
141 may be spread over multiple lines. If several features with
142 different descriptions are being documented in the same
143 manual page, the following form is therefore
144 used:
145
146
147 .SH NAME
148 foo, bar - programs to do something
149 .br
150 baz - program to do nothing
151
152
153 (A macro which starts a new paragraph, like .PP,
154 may be used instead of the break macro
155 .br.)
156
157
158 There are several common reasons why whatis parsing fails.
159 Sometimes authors of manual pages replace `.SH NAME' with
160 `.SH MYPROGRAM', and then __mandb__ cannot find the
161 section from which to extract the information it needs.
162 Sometimes authors include a NAME section, but place
163 free-form text there rather than `name - description'.
164 However, any syntax resembling the above should be
165 accepted.
166 !!SEE ALSO
167
168
169 man(1), mandb(8), apropos(1),
170 whatis(1).
171 !!NOTES
172
173
174 __lexgrog__ cannot parse files containing .so requests.
175 These are probably best checked by other problems, as
176 __lexgrog__ often does not have enough context to know
177 what to do with them.
178 !!AUTHOR
179
180
181 The code used by __lexgrog__ to scan man pages was
182 written by:
183
184
185 Wilf. (G.Wilford@ee.surrey.ac.uk).
186 Fabrizio Polacco (fpolacco@debian.org).
187 Colin Watson (cjwatson@debian.org).
188 Colin Watson wrote the current incarnation of the command-line front-end, as well as this man page.
189 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.