337 lines
6.8 KiB
HTML
337 lines
6.8 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of LEXGROG</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>LEXGROG</H1>
|
|
Section: Manual pager utils (1)<BR>Updated: 2020-02-25<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
lexgrog - parse header information in man pages
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<B>lexgrog</B>
|
|
|
|
[<B>-m</B>|<B>-c</B>]
|
|
|
|
[<B>-dfw?V</B>]
|
|
|
|
[<B>-E</B>
|
|
|
|
<I>encoding</I>]
|
|
|
|
<I>file</I>
|
|
|
|
...
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
<B>lexgrog</B>
|
|
|
|
is an implementation of the traditional "groff guess" utility in
|
|
<B>lex</B>.
|
|
|
|
It reads the list of files on its command line as either man page source
|
|
files or preformatted "cat" pages, and displays their name and
|
|
description as used by
|
|
<B>apropos</B>
|
|
|
|
and
|
|
<B>whatis</B>,
|
|
|
|
the list of preprocessing filters required by the man page before it is
|
|
passed to
|
|
<B>nroff</B>
|
|
|
|
or
|
|
<B>troff</B>,
|
|
|
|
or both.
|
|
<P>
|
|
|
|
If its input is badly formatted,
|
|
<B>lexgrog</B>
|
|
|
|
will print "parse failed"; this may be useful for external
|
|
programs that need to check man pages for correctness.
|
|
If one of
|
|
<B>lexgrog</B>'s
|
|
|
|
input files is "-", it will read from standard input; if any input
|
|
file is compressed, a decompressed version will be read automatically.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>OPTIONS</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="1"><B>-d</B>, <B>--debug</B>
|
|
|
|
<DD>
|
|
Print debugging information.
|
|
<DT id="2"><B>-m</B>, <B>--man</B>
|
|
|
|
<DD>
|
|
Parse input as man page source files.
|
|
This is the default if neither
|
|
<B>--man</B>
|
|
|
|
nor
|
|
<B>--cat</B>
|
|
|
|
is given.
|
|
<DT id="3"><B>-c</B>, <B>--cat</B>
|
|
|
|
<DD>
|
|
Parse input as preformatted man pages ("cat pages").
|
|
<B>--man</B>
|
|
|
|
and
|
|
<B>--cat</B>
|
|
|
|
may not be given simultaneously.
|
|
<DT id="4"><B>-w</B>, <B>--whatis</B>
|
|
|
|
<DD>
|
|
Display the name and description from the man page's header, as used by
|
|
<B>apropos</B>
|
|
|
|
and
|
|
<B>whatis</B>.
|
|
|
|
This is the default if neither
|
|
<B>--whatis</B>
|
|
|
|
nor
|
|
<B>--filters</B>
|
|
|
|
is given.
|
|
<DT id="5"><B>-f</B>, <B>--filters</B>
|
|
|
|
<DD>
|
|
Display the list of filters needed to preprocess the man page before
|
|
formatting with
|
|
<B>nroff</B>
|
|
|
|
or
|
|
<B>troff</B>.
|
|
|
|
<DT id="6"><B>-E</B> <I>encoding</I>, <B>--encoding</B> <I>encoding</I><DD>
|
|
Override the guessed character set for the page to
|
|
<I>encoding</I>.
|
|
|
|
<DT id="7"><B>-?</B>, <B>--help</B>
|
|
|
|
<DD>
|
|
Print a help message and exit.
|
|
<DT id="8"><B>--usage</B>
|
|
|
|
<DD>
|
|
Print a short usage message and exit.
|
|
<DT id="9"><B>-V</B>, <B>--version</B>
|
|
|
|
<DD>
|
|
Display version information.
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>EXIT STATUS</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="10"><B>0</B>
|
|
|
|
<DD>
|
|
Successful program execution.
|
|
<DT id="11"><B>1</B>
|
|
|
|
<DD>
|
|
Usage error.
|
|
<DT id="12"><B>2</B>
|
|
|
|
<DD>
|
|
<B>lexgrog</B>
|
|
|
|
failed to parse one or more of its input files.
|
|
</DL>
|
|
<A NAME="lbAG"> </A>
|
|
<H2>EXAMPLES</H2>
|
|
|
|
<PRE>
|
|
$ 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
|
|
</PRE>
|
|
|
|
<A NAME="lbAH"> </A>
|
|
<H2>WHATIS PARSING</H2>
|
|
|
|
<B>mandb</B>
|
|
|
|
(which uses the same code as
|
|
<B>lexgrog</B>)
|
|
|
|
parses the
|
|
<B>NAME</B>
|
|
|
|
section at the top of each manual page looking for names and descriptions
|
|
of the features documented in each.
|
|
While the parser is quite tolerant, as it has to cope with a number of
|
|
different forms that have historically been used, it may sometimes fail to
|
|
extract the required information.
|
|
<P>
|
|
|
|
When using the traditional
|
|
<I>man</I>
|
|
|
|
macro set, a correct
|
|
<B>NAME</B>
|
|
|
|
section looks something like this:
|
|
<P>
|
|
|
|
<DL COMPACT><DT id="13"><DD>
|
|
|
|
<PRE>
|
|
.SH NAME
|
|
foo \- program to do something
|
|
</PRE>
|
|
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
|
|
Some manual pagers require the '\-' to be exactly as shown;
|
|
<B>mandb</B>
|
|
|
|
is more tolerant, but for compatibility with other systems it is
|
|
nevertheless a good idea to retain the backslash.
|
|
<P>
|
|
|
|
On the left-hand side, there may be several names, separated by commas.
|
|
Names containing whitespace will be ignored to avoid pathological behaviour
|
|
on certain ill-formed
|
|
<B>NAME</B>
|
|
|
|
sections.
|
|
The text on the right-hand side is free-form, and may be spread over
|
|
multiple lines.
|
|
If several features with different descriptions are being documented in the
|
|
same manual page, the following form is therefore used:
|
|
<P>
|
|
|
|
<DL COMPACT><DT id="14"><DD>
|
|
|
|
<PRE>
|
|
.SH NAME
|
|
foo, bar \- programs to do something
|
|
.br
|
|
baz \- program to do nothing
|
|
</PRE>
|
|
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
|
|
(A macro which starts a new paragraph, like <TT>.PP</TT>, may be used instead
|
|
of the break macro <TT>.br</TT>.)
|
|
<P>
|
|
|
|
When using the BSD-derived
|
|
<I>mdoc</I>
|
|
|
|
macro set, a correct
|
|
<B>NAME</B>
|
|
|
|
section looks something like this:
|
|
<P>
|
|
|
|
<DL COMPACT><DT id="15"><DD>
|
|
|
|
<PRE>
|
|
.Sh NAME
|
|
.Nm foo
|
|
.Nd program to do something
|
|
</PRE>
|
|
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
There are several common reasons why whatis parsing fails.
|
|
Sometimes authors of manual pages replace '.SH NAME' with
|
|
'.SH MYPROGRAM', and then
|
|
<B>mandb</B>
|
|
|
|
cannot find the section from which to extract the information it needs.
|
|
Sometimes authors include a NAME section, but place free-form text there
|
|
rather than 'name \- description'.
|
|
However, any syntax resembling the above should be accepted.
|
|
<A NAME="lbAI"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<I><A HREF="/cgi-bin/man/man2html?1+apropos">apropos</A></I>(1),
|
|
|
|
<I><A HREF="/cgi-bin/man/man2html?1+man">man</A></I>(1),
|
|
|
|
<I><A HREF="/cgi-bin/man/man2html?1+whatis">whatis</A></I>(1),
|
|
|
|
<I><A HREF="/cgi-bin/man/man2html?8+mandb">mandb</A></I>(8)
|
|
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>NOTES</H2>
|
|
|
|
<B>lexgrog</B>
|
|
|
|
attempts to parse files containing .so requests, but will only be able
|
|
to do so correctly if the files are properly installed in a manual page
|
|
hierarchy.
|
|
<A NAME="lbAK"> </A>
|
|
<H2>AUTHOR</H2>
|
|
|
|
The code used by
|
|
<B>lexgrog</B>
|
|
|
|
to scan man pages was written by:
|
|
<P>
|
|
|
|
<PRE>
|
|
Wilf. (<A HREF="mailto:G.Wilford@ee.surrey.ac.uk">G.Wilford@ee.surrey.ac.uk</A>).
|
|
Fabrizio Polacco (<A HREF="mailto:fpolacco@debian.org">fpolacco@debian.org</A>).
|
|
Colin Watson (<A HREF="mailto:cjwatson@debian.org">cjwatson@debian.org</A>).
|
|
</PRE>
|
|
|
|
<P>
|
|
|
|
Colin Watson wrote the current incarnation of the command-line
|
|
front-end, as well as this man page.
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="16"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="17"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="18"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="19"><A HREF="#lbAE">OPTIONS</A><DD>
|
|
<DT id="20"><A HREF="#lbAF">EXIT STATUS</A><DD>
|
|
<DT id="21"><A HREF="#lbAG">EXAMPLES</A><DD>
|
|
<DT id="22"><A HREF="#lbAH">WHATIS PARSING</A><DD>
|
|
<DT id="23"><A HREF="#lbAI">SEE ALSO</A><DD>
|
|
<DT id="24"><A HREF="#lbAJ">NOTES</A><DD>
|
|
<DT id="25"><A HREF="#lbAK">AUTHOR</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:18 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|