Initial revision

1 files changed, 211 insertions, 0 deletions

diff --git a/lid.1 b/lid.1
new file mode 100644
index 0000000..ce98212
--- /dev/null
+++ b/lid.1
@@ -0,0 +1,211 @@
+.TH LID 1
+.SH NAME
+lid, gid, eid, aid, pid \- query id database
+.SH SYNOPSIS
+.B lid
+.RB [ \-f \^file]
+.RB [ \-u \^n]
+.RB [ \-r \^dir]
+.RB [ \-edoxamseknc]
+patterns...
+.PP
+.B gid
+.RB [ \-f \^file]
+.RB [ \-r \^dir]
+.RB [ \-edoxamsec]
+patterns...
+.PP
+.B eid
+.RB [ \-f \^file]
+.RB [ \-r \^dir]
+.RB [ \-doxamsec]
+patterns...
+.PP
+.B aid
+.RB [ \-f \^file]
+.RB [ \-r \^dir]
+.RB [ \-doxamsc]
+patterns...
+.PP
+.B pid
+.RB [ \-f \^file]
+.RB [ \-r \^dir]
+.RB [ \-ekncb]
+patterns...
+.SH DESCRIPTION
+These commands provide a flexible query interface to the
+.I id
+database.
+.I Lid\^
+does a lookup on
+.IR patters
+and prints out lines in this way:
+.PP
+.nf
+idname        ../hdir/hfile.h ../cdir/{cfile1,cfile2}.c
+.fi
+.PP
+Notice that multiple files with the same directory prefix
+and suffix are concatenated in the globbing-set-notation of
+.IR csh (1).
+Also notice that all of the
+.I id
+database query commands adjust the list of pathnames to be relative
+to your current working directory, provided that
+.IR mkid (1)
+was used to build the database, and your working directory
+is located within the sub-tree covered by the
+.I id
+database.
+.PP
+If multiple names match on pattern, then there will be one line
+of output per name.  The mnemonic significance of the name is
+\fI\|l(ookup) id\fP.
+.PP
+.I Gid
+does a lookup and then searches for the names it matches in the
+files where they occur.  The mnemonic for this name is
+\fI\|g(rep)id\fP. 
+.PP
+.I Eid
+does a lookup, and then invokes an editor on all files with
+the matched name as an initial search string.  Of course, this
+name stands for
+\fI\|e(dit) id\fP.
+.PP
+.I Eid
+uses four environment variables to control its invocation of the
+editor.
+Naturally,
+.B EDITOR
+is used to locate the editing program.
+.B EIDARG
+is a
+.IR printf (3S)
+string used to specify the form of the initial-search-string
+argument.  If the editor does not support such an argument,
+this variable may be left unset.
+.B EIDLDEL
+and
+.B EIDRDEL
+specify the form of the left and right word-delimiters respectively.
+The best way to explain the use of these last three variables is
+with an example.  Here are the proper settings for vi(1):
+.nf
+EIDARG='+/%s/'	# initial search argument template
+EIDLDEL='\\<'	# left word-delimiter
+EIDRDEL='\\>'	# right word-delimiter
+.fi
+.PP
+.I Patterns
+may be simple alpha-numeric strings, or regular expressions in the
+style of
+.IR regcmp (3).
+If the string contains no regular-expression meta-characters, it is
+searched for as a
+.IR word .
+If the string contains meta-characters, or if the \-e argument is
+supplied, it is searched for as regular-expression.
+.PP
+.I Aid\^
+produces output in the style of
+.I lid\^
+but its pattern arguments are searched for as substrings within
+the identifiers in the database.  No regular-expression search
+is performed, even if the pattern contains meta-characters.
+The search is conducted in an alphabetic case insensitive manner.
+The mnemonic for this name is
+\fI\|a(propos) id\fP. 
+.PP
+.I Pid\^
+is used to match the input patterns against the names of the files
+in the database rather than the contents of the files. The pattern
+is assumed to be a simple shell wild card pattern unless the
+.B \-e
+option is given, in which case full regular expression matching
+is used.
+The
+.B \-b
+option can be used to restrict the match to just the basename portion
+of the full absolute path name of the file.
+The mnemonic for this name is
+\fI\|p(ath) id\fP. 
+.PP
+The following options are recognized:
+.TP 10
+.BR \-f file\^
+Use
+.I file\^
+as the database instead of the default
+.BR ID .
+.TP 10
+.BR \-u n
+Lists all identifiers in the database that are non-unique within the first
+.I n
+characters.  This facility is particularly helpful when porting a program
+to a system whose compiler or linker has fewer significant characters
+for identifiers.
+.TP 10
+.BR \-r dir\^
+Assume the names stored in the database are relative to this directory.
+This option is useful if you create the database in one place, then move
+it somewhere else. Normally all the query tools assume the names in
+the database are relative to the location of the database.
+.TP 10
+.B \-c
+This option is similar to
+.BR \-r ,
+but it tells the id query tool to assume the names in the ID database
+are stored relative to the current working directory.
+.TP 10
+.B \-k
+Suppresses the use of \fL{\fP and \fL}\fP as a shorthand in the
+generated list of file names. Each name is output in full.
+.TP 10
+.B \-n
+Suppresses printing the name of the search string, only the names of
+the files containing the string are printed. Together with the \fB\-k\fP
+option this can be used to generate lists of files to pass to other
+programs.
+.PP
+.TP 10
+.B \-b
+In the
+.I pid
+program, the
+.B \-b
+option is used to force pattern matching on just the base names of the
+file, otherwise the pattern matching is done on the full absolute file
+name.
+.PP
+The remaining options are for use in conjunction with numeric patterns:
+.TP 10
+.B \-doxa
+These options may be specified in any combination.
+They limit numeric matches to specific radixes.
+The
+.BR \-d ,
+.BR \-o ,
+and
+.B \-x
+options limit matches to decimal, octal, and hexadecimal respectively.
+The
+.BR \-a
+option is a shorthand for specifying all three radixes.
+.PP
+Searches for numbers 
+are conducted numerically rather than lexically, so that all
+representations for a given number are potentially available
+from a single search.
+.TP 10
+.B \-m
+Merge multiple lines of output into a single line.
+.TP 10
+.B \-s
+Limit the results of the search to identifiers that occur only
+once in the entire set of sources covered by the database.
+This option is useful for finding identifiers that are defined
+but never used.
+.SH SEE ALSO
+mkid(1),
+fid(1).