Classic Shell Scripting - Arnold Robbins [228]
.PP
To avoid confusion with options, if a filename begins with a
hyphen, it must be disguised by a leading absolute or
relative directory path, e.g.,
.I /tmp/-foo
or
.IR ./-foo .
.\" --------------------------------------------------------
.TP \w'\fB\-\^\-version\fP'u+3n
.B \-all
Search all directories for each specified file, instead of
reporting just the first instance of each found in the
search path.
.\" --------------------------------------------------------
.TP
.B \-?
Same as
.BR \-help .
.\" --------------------------------------------------------
.TP
.B \-help
Display a brief help message on
.IR stdout ,
giving a usage description, and then terminate immediately
with a success return code.
.\" --------------------------------------------------------
.TP
.B \-version
Display the program version number and release date on
.IR stdout ,
and then terminate immediately with a success return code.
.\" = = = = = = = = = = = = = = = = = = = = = = = = = = =
= = = = = = = = = = = = = = = = = = = = = = = = = = = = =
.SH DESCRIPTION
.B pathfind
searches a colon-separated directory search path defined by
the value of the environment variable, \fIenvvar\fP, for
specified files or file patterns, reporting their full path on
.IR stdout ,
or complaining \fIfilename: not found\fP on
.I stderr
if a file cannot be found anywhere in the search path.
.PP
.BR pathfind 's
exit status is 0 on success, and otherwise is the number of
files that could not be found, possibly capped at the
exit code limit of 125.
.PP
For example,
.RS
.nf
\&\fCpathfind PATH ls\fP
.fi
.RE
reports
.RS
.nf
\&\fC/bin/ls\fP
.fi
.RE
on most Unix systems, and
.RS
.nf
\&\fCpathfind --all PATH gcc g++\fP
.fi
.RE
reports
.RS
.nf
\&\fC/usr/local/bin/gcc
/usr/bin/gcc
/usr/local/gnat/bin/gcc
/usr/local/bin/g++
/usr/bin/g++\fP
.fi
.RE
on some systems.
.PP
Wildcard patterns also work:
.RS
.nf
\&\fCpathfind --all PATH '??tex'\fP
.fi
.RE
reports
.RS
.nf
\&\fC/usr/local/bin/detex
/usr/local/bin/dotex
/usr/local/bin/latex
/usr/bin/latex\fP
.fi
.RE
on some systems.
.\" = = = = = = = = = = = = = = = = = = = = = = = = = = =
= = = = = = = = = = = = = = = = = = = = = = = = = = = = =
.SH "SEE ALSO"
.BR find (1),
.BR locate (1),
.BR slocate (1),
.BR type (1),
.BR whence (1),
.BR where (1),
.BR whereis (1).
.\" = = = = = = = = = = = = = = = = = = = = = = = = = = =
= = = = = = = = = = = = = = = = = = = = = = = = = = = = =
* * *
[1] Although nroff was developed before troff, from the user's point of view, both systems are similar: ditroff and groff each emulate both of them.
[2] See Robert J. Chassell and Richard M. Stallman, Texinfo: The GNU Documentation Format, Free Software Foundation, 1999, ISBN 1-882114-67-1.
[3] See Donald E. Knuth, The TEXbook, Addison-Wesley, 1984, ISBN 0-201-13448-9.
[4] See http://www.troff.org/.
[5] See http://www.gnu.org/software/texinfo/.
[6] See http://www.tldp.org/.
[7] Available at http://www.math.utah.edu/pub/man2html/ and http://www.math.utah.edu/pub/man2texi/.
Manual-Page Syntax Checking
Checking correct formatting of manual pages is usually done visually, with printed output from either of these commands:
groff -man -Tps pathfind.man | lp
troff -man -Tpost pathfind.man | /usr/lib/lp/postscript/dpost | lp
or on the screen as ASCII or typeset material, with commands like this:
nroff -man pathfind.man | col | more
groff -man -Tascii pathfind.man | more
groff -man -TX100 pathfind.man &
The col command handles certain special escape sequences that nroff generates for horizontal and vertical motion. col is not needed for groff output.
Some Unix systems have a simple-minded syntax checker, checknr; the command:
checknr pathfind.man
produces no complaints on our systems. checknr is good at catching font mismatches, but knows little about the manual-page format.
Most Unix systems have deroff, which is a simple filter that strips troff markup. You can do a spellcheck like this:
deroff pathfind.man