Path: utzoo!utgpu!cs.utexas.edu!sdd.hp.com!wuarchive!rex!uflorida!travis!tom
From: tom@ssd.csd.harris.com (Tom Horsley)
Newsgroups: alt.sources
Subject: mkid 04/11 (identifier cross reference tool)
Message-ID: <TOM.90Dec12094212@hcx2.ssd.csd.harris.com>
Date: 12 Dec 90 14:42:12 GMT
Sender: news@travis.csd.harris.com
Organization: Harris Computer Systems Division
Lines: 701

#! /bin/sh
# This is a shell archive.  Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file".  To overwrite existing
# files, type "sh file -c".  You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g..  If this archive is complete, you
# will see the following message at the end:
#		"End of archive 4 (of 11)."
# Contents:  iid.1 lid.1 mkid.1
# Wrapped by tom@hcx2 on Wed Dec 12 07:21:56 1990
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'iid.1' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'iid.1'\"
else
echo shar: Extracting \"'iid.1'\" \(5306 characters\)
sed "s/^X//" >'iid.1' <<'END_OF_FILE'
X.TH IID 1
X.SH NAME
Xiid \- interactive query for ID database
X.SH SYNOPSIS
X.PP
X.B iid
X.RB [ \-a]
X.RB [ \-c \^command]
X.RB [ \-H]
X.SH DESCRIPTION
XThis command provides an interactive query interface to the
X.I ID
Xdatabase.
X.I Iid\^
Xallows you to query an
X.I ID
Xdatabase in a fashion similar to using \fIDIALOG\fP. Any individual
Xquery command results in a list of files that satisfy that query,
Xeach set of files is retained by
X.I iid
Xand assigned a set number. The sets may be combined with
X.IR AND ,
X.I OR
Xand
X.I NOT
Xoperators to produce additional sets. The primitive operators that
Xproduce sets are invocations of the
X.I lid
Xor
X.I aid
Xprograms.
X.SH OPTIONS
XNormally
X.I iid
Xruns interactively. Options may be used to run it in batch mode.
X.TP 8
X.B \-a
XUse the
X.I aid
Xprogram as the default query program, normally
X.I lid
Xis used.
X.TP 8
X.B \-c
XAccept a single command as an argument, run that command, and exit
X.IR Iid .
X.TP
X.B \-H
XPrint a brief help message and exit.
X.SH SUBCOMMANDS
XThe subcommands are used to carry on a dialog with
X.I iid
Xafter invoking the program.
X.PP
XTwo basic query commands are available:
X.B SS
Xand
X.BR FILES .
XThe
X.B SS
Xcommand shows the sets generated by a query, but does not display
Xthe actual file names that satisfy the query.
XThe
X.B FILES
Xcommand only displays the list of files, it does not show any
Xof the sets created during the query.
X.PP
XQueries consist of keywords and identifier strings. The keywords are:
X.B and or not lid aid match
Xand
X.B s<number>
Xwhere
X.B s<number>
Xis a set number consisting of the letter
X.B s
Xfollowed (with no space) by a decimal set number.
XA clause of the form
X.B lid <identifier list>
Xinvokes
X.I lid
Xwith the
X.B <identifier list>
Xas arguments and produces a set of files as a result.
XSubstituting
X.B aid
Xfor
X.B lid
Xruns the
X.I aid
Xprogram to generate the list of files.
XAs a shorthand notation for
X.B lid <identifier>
Xyou may simply use
X.B <identifier>.
XThe
X.B match
Xoperator runs the standard system
X.I ls
Xutility to produce a set of files. This allows sets to be
Xconstructed based on the names of files (using wild cards)
Xrather than contents.
XThe
X.B and or
Xand
X.B not
Xoperators can be used to combine sets in the obvious fashion.
XIf you need to pass any of the keywords as actual arguments to
Xprograms, or if the search strings contain any shell escape
Xcharacters place the argument in quotes.
X.PP
XThe
X.B NOT
Xoperator has highest precedence, followed by
X.B AND
Xand
X.B OR
Xin that order. Parenthesis may be used for grouping.
X.PP
XThe remaining commands are:
X.PP
X.B BEGIN <directory>
Xaccepts a directory name and switches to that directory. By changing
Xdirectories you control which
X.I ID
Xdatabase is searched. Changing directories automatically deletes
Xall the sets constructed so far. The
X.B BEGIN
Xcommand may be abbreviated as
X.BR B .
X.PP
X.B SETS
Xshows the description of all the sets created so far. Each set
Xdescription has the set number, the number of files in the set,
Xand a symbolic description of the query that created the set.
X.PP
X.B SHOW <set number>
Xruns a pager program, passing as arguments all the files in
Xthe specified set. The pager program comes from the
X.B $PAGER
Xenvironment variable. This command may be abbreviated
X.BR P .
X.PP
X.B HELP
Xruns the pager on the help file. The commands
X.B H
Xand
X.B ?
Xalso act as help commands.
X.PP
X.B OFF
Xexits the program.
X.B Q
Xis short for
X.BR OFF .
X.PP
XAll commands and keywords are case insensitive, so that
X.B SHOW ShOW
Xand
X.B show
Xall work equally well.
X.SH INTERFACE
XTwo forms of commands are provided for interface with arbitrary
Xprograms. Any command that is not recognized as one
Xof the above built in
X.I iid
Xcommands, is assumed to be a program which, when run, will print
Xa list of file names.
X.I Iid
Xruns the command as typed, and records the output as a new set
Xwhich may be combined with other sets in subsequent queries.
X.PP
XIf the command starts with a
X.BR !,
X.I iid
Xstrips off the leading
X.B !
Xand simply runs the command. Any output goes to stdout and
Xis not recorded as a set.
X.PP
XIn both types of shell commands, any set numbers specified as
Xarguments are expanded into a list of file names before running
Xthe command.
X.SH EXAMPLE
X.nf
X.ft L
X===> iid
Xiid> ss lid "^get" or lid "Arg$"
X   S0     14  lid -kmn "^get"
X   S1      3  lid -kmn "Arg$"
X   S2     15  (lid -kmn "^get") OR (lid -kmn "Arg$")
Xiid> f s1
Xlid.c
Xpaths.c
Xinit.c
Xiid> off
X.FT P
X.fi
X.EX off
X.PP
XIn this example the
X.B ss
Xcommand displays the sets it creates as it
Xdoes the parts of the query. In this case 3 sets are created, set S0
Xhas 14 files in it, set S1 has 3 files and the union of the two sets,
XS2, has 15 files. A description of the query that created any given
Xset is kept along with the set and displayed when sets are printed.
X.PP
XThe
X.B f s1
Xcommand lists the three files in set S1.
X.PP
XThe 
X.B off
Xcommand terminates the example session.
X.SH HINTS
XThe shell interface commands can be used to generate file sets by
Xrunning the
X.I find
Xor
X.I ls
Xutilities, or compiles of a selected group of files can be done
Xusing the
X.BR ! cc
Xcommand with a set number as the argument.
X.BR ! lp
Xcan be used to print a selected group of files.
X.PP
XThis program interfaces nicely with
X.I emacs
Xif you run the server program and specify the client program
Xas your $PAGER.
X.SH SEE ALSO
Xmkid(1),
Xlid(1),
Xaid(1).
END_OF_FILE
if test 5306 -ne `wc -c <'iid.1'`; then
    echo shar: \"'iid.1'\" unpacked with wrong size!
fi
# end of 'iid.1'
fi
if test -f 'lid.1' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'lid.1'\"
else
echo shar: Extracting \"'lid.1'\" \(5678 characters\)
sed "s/^X//" >'lid.1' <<'END_OF_FILE'
X.TH LID 1
X.SH NAME
Xlid, gid, eid, aid, pid \- query id database
X.SH SYNOPSIS
X.B lid
X.RB [ \-f \^file]
X.RB [ \-u \^n]
X.RB [ \-r \^dir]
X.RB [ \-edoxamseknc]
Xpatterns...
X.PP
X.B gid
X.RB [ \-f \^file]
X.RB [ \-r \^dir]
X.RB [ \-edoxamsec]
Xpatterns...
X.PP
X.B eid
X.RB [ \-f \^file]
X.RB [ \-r \^dir]
X.RB [ \-doxamsec]
Xpatterns...
X.PP
X.B aid
X.RB [ \-f \^file]
X.RB [ \-r \^dir]
X.RB [ \-doxamsc]
Xpatterns...
X.PP
X.B pid
X.RB [ \-f \^file]
X.RB [ \-r \^dir]
X.RB [ \-ekncb]
Xpatterns...
X.SH DESCRIPTION
XThese commands provide a flexible query interface to the
X.I id
Xdatabase.
X.I Lid\^
Xdoes a lookup on
X.IR patters
Xand prints out lines in this way:
X.PP
X.nf
Xidname        ../hdir/hfile.h ../cdir/{cfile1,cfile2}.c
X.fi
X.PP
XNotice that multiple files with the same directory prefix
Xand suffix are concatenated in the globbing-set-notation of
X.IR csh (1).
XAlso notice that all of the
X.I id
Xdatabase query commands adjust the list of pathnames to be relative
Xto your current working directory, provided that
X.IR mkid (1)
Xwas used to build the database, and your working directory
Xis located within the sub-tree covered by the
X.I id
Xdatabase.
X.PP
XIf multiple names match on pattern, then there will be one line
Xof output per name.  The mnemonic significance of the name is
X\fI\|l(ookup) id\fP.
X.PP
X.I Gid
Xdoes a lookup and then searches for the names it matches in the
Xfiles where they occur.  The mnemonic for this name is
X\fI\|g(rep)id\fP. 
X.PP
X.I Eid
Xdoes a lookup, and then invokes an editor on all files with
Xthe matched name as an initial search string.  Of course, this
Xname stands for
X\fI\|e(dit) id\fP.
X.PP
X.I Eid
Xuses four environment variables to control its invocation of the
Xeditor.
XNaturally,
X.B EDITOR
Xis used to locate the editing program.
X.B EIDARG
Xis a
X.IR printf (3S)
Xstring used to specify the form of the initial-search-string
Xargument.  If the editor does not support such an argument,
Xthis variable may be left unset.
X.B EIDLDEL
Xand
X.B EIDRDEL
Xspecify the form of the left and right word-delimiters respectively.
XThe best way to explain the use of these last three variables is
Xwith an example.  Here are the proper settings for vi(1):
X.nf
XEIDARG='+/%s/'	# initial search argument template
XEIDLDEL='\\<'	# left word-delimiter
XEIDRDEL='\\>'	# right word-delimiter
X.fi
X.PP
X.I Patterns
Xmay be simple alpha-numeric strings, or regular expressions in the
Xstyle of
X.IR regcmp (3).
XIf the string contains no regular-expression meta-characters, it is
Xsearched for as a
X.IR word .
XIf the string contains meta-characters, or if the \-e argument is
Xsupplied, it is searched for as regular-expression.
X.PP
X.I Aid\^
Xproduces output in the style of
X.I lid\^
Xbut its pattern arguments are searched for as substrings within
Xthe identifiers in the database.  No regular-expression search
Xis performed, even if the pattern contains meta-characters.
XThe search is conducted in an alphabetic case insensitive manner.
XThe mnemonic for this name is
X\fI\|a(propos) id\fP. 
X.PP
X.I Pid\^
Xis used to match the input patterns against the names of the files
Xin the database rather than the contents of the files. The pattern
Xis assumed to be a simple shell wild card pattern unless the
X.B \-e
Xoption is given, in which case full regular expression matching
Xis used.
XThe
X.B \-b
Xoption can be used to restrict the match to just the basename portion
Xof the full absolute path name of the file.
XThe mnemonic for this name is
X\fI\|p(ath) id\fP. 
X.PP
XThe following options are recognized:
X.TP 10
X.BR \-f file\^
XUse
X.I file\^
Xas the database instead of the default
X.BR ID .
X.TP 10
X.BR \-u n
XLists all identifiers in the database that are non-unique within the first
X.I n
Xcharacters.  This facility is particularly helpful when porting a program
Xto a system whose compiler or linker has fewer significant characters
Xfor identifiers.
X.TP 10
X.BR \-r dir\^
XAssume the names stored in the database are relative to this directory.
XThis option is useful if you create the database in one place, then move
Xit somewhere else. Normally all the query tools assume the names in
Xthe database are relative to the location of the database.
X.TP 10
X.B \-c
XThis option is similar to
X.BR \-r ,
Xbut it tells the id query tool to assume the names in the ID database
Xare stored relative to the current working directory.
X.TP 10
X.B \-k
XSuppresses the use of \fL{\fP and \fL}\fP as a shorthand in the
Xgenerated list of file names. Each name is output in full.
X.TP 10
X.B \-n
XSuppresses printing the name of the search string, only the names of
Xthe files containing the string are printed. Together with the \fB\-k\fP
Xoption this can be used to generate lists of files to pass to other
Xprograms.
X.PP
X.TP 10
X.B \-b
XIn the
X.I pid
Xprogram, the
X.B \-b
Xoption is used to force pattern matching on just the base names of the
Xfile, otherwise the pattern matching is done on the full absolute file
Xname.
X.PP
XThe remaining options are for use in conjunction with numeric patterns:
X.TP 10
X.B \-doxa
XThese options may be specified in any combination.
XThey limit numeric matches to specific radixes.
XThe
X.BR \-d ,
X.BR \-o ,
Xand
X.B \-x
Xoptions limit matches to decimal, octal, and hexadecimal respectively.
XThe
X.BR \-a
Xoption is a shorthand for specifying all three radixes.
X.PP
XSearches for numbers 
Xare conducted numerically rather than lexically, so that all
Xrepresentations for a given number are potentially available
Xfrom a single search.
X.TP 10
X.B \-m
XMerge multiple lines of output into a single line.
X.TP 10
X.B \-s
XLimit the results of the search to identifiers that occur only
Xonce in the entire set of sources covered by the database.
XThis option is useful for finding identifiers that are defined
Xbut never used.
X.SH SEE ALSO
Xmkid(1),
Xfid(1).
END_OF_FILE
if test 5678 -ne `wc -c <'lid.1'`; then
    echo shar: \"'lid.1'\" unpacked with wrong size!
fi
# end of 'lid.1'
fi
if test -f 'mkid.1' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'mkid.1'\"
else
echo shar: Extracting \"'mkid.1'\" \(5564 characters\)
sed "s/^X//" >'mkid.1' <<'END_OF_FILE'
X.TH MKID 1
X.SH NAME
Xmkid \- make an id database
X.SH SYNOPSIS
X.B mkid
X.RB [ \-v ]
X.RB [ \-f \^out-file]
X.RB [ \-s \^directory]
X.RB [ \-r \^directory]
X.RB [ \-S \^scanarg]
X.RB [ \-a \^arg-file]
X.RB [ \- ]
X.RB [ \-u ]
X.RB [ files... ]
X.SH DESCRIPTION
X.I Mkid\^
Xbuilds a database that stores numbers and identifier names, as well
Xas the names of the files in which they occur.
X.I Mkid\^
Xis particularly useful with large programs spread out across multiple
Xsource files.  It serves as an aid for program maintenance and as a
X.I guide\^
Xfor perusing a program.
X.PP
XThe following options are recognized:
X.TP 10
X.B \-v
XVerbose.
XReport
X.IR mkid 's
Xprogress in building the database.  The output comes on standard error.
X.TP 10
X.BI \-f out-file\^
XWrite the finished database into
X.IR out-file .
X.B ID\^
Xis the default.
XNormally the names of the files scanned are written to the database
Xas specified in the argument list. If the database sepcified with
X.B \-f
Xis not located in the current directory, then the file names are
Xadjusted so that they are relative to the directory that the
Xdatabase is located in.
X.TP 10
X.BI \-s directory\^
X.TP 10
X.BI \-r directory\^
XIf
X.IR mkid 's
Xattempt to open a source-file fails, it will try to checkout the
Xcorresponding SCCS or RCS file if present.  The
X.B \-s
Xoption tells
X.I mkid\^
Xwhich directory holds the SCCS file.
XSimilarly, the
X.B \-r
Xoption tells
X.I mkid\^
Xwhich directory holds the RCS file.
XIf neither the RCS or SCCS directories are specified,
X.I mkid\^
Xwill first look for an SCCS file in the current directory, then in
X.BI sccs ,
Xand finally in
X.BI SCCS .
XIt will then look for an RCS file in the current directory, and finally in
X.BI RCS .
X.TP 10
X.BI \-a arg-file\^
XOpen and read
X.I arg-file\^
Xin order to obtain a list of source file arguments.  Source file names
Xmust appear one to a line.
X.BI \-S ,
X.BI \-r ,
Xand
X.BI \-s
Xarguments may also be placed one per line in
X.IR file .
XThey are distinguished from source file names by their leading `-'.  If a file name begins
Xwith `-', it can be distinguished from an argument by explicitly prepending the current
Xdirectory string: `./'.
X.TP 10
X.B \-
XThis operates in the same manner as the
X.B \-a
Xoption described above, but reads from the standard input instead of a file.
X.TP 10
X.B \-u
XUpdate an existing database.  Only those files that have been modified
Xsince the database was built will be rescanned.  This is a significant
Xtime-saver for updating large databases where few sources have changed.
X.TP 10
X.B files...
XIf neither the
X.BI \-a ,
X.BI \- ,
Xnor
X.BI \-u ,
Xarguments have been specified, take file names from the command line.
X.TP 10
X.BI \-S scanarg\^
X.I Mkid\^
Xscans source files in order to obtain numbers and identifier names.
XSince the lexical rules of languages differ,
X.I mkid\^
Xapplies a different scanning function to each language in order
Xto conform to that language's lexical rules.
X.I Mkid\^
Xdetermines the source file's language by examining its filename
Xsuffix which commonly occurs after a dot (`.').
XThe
X.B \-S
Xargument is a way of passing language specific arguments to the
Xscanner for that language.  This argument takes a number of forms:
X.br
X-S<suffix>=<language>
X.br
X-S<language>-<arg>
X.br
X+S-<arg>
X.br
X-S<lang>/<lang>/<filter>
X.br
XThe first form associates a suffix with a language.
XFor example -S.c=vhil would cause all .c files to be scanned
Xas though they were language vhil rather than c.
XYou may find
Xout which suffixes are defined for which languages with the following
Xoptions: `-S<suffix>=?' tells which language is bound to
X.IR <suffix> ,
X`-S?=<language>' tells which suffixes are bound to 
X.IR <language> ,
Xand `-S?=?' reports all bindings between suffixes and languages.
X.PP
XThe second form passes an argument for processing by the scanner
Xfor a specific language.  The third form passes an argument to
Xall scanners.
X.PP
XFinally, the <lang>/<lang>/<filter> form defines a shell command
Xto filter the file with. This can be used to run an arbitrary
Xprogram to filter the contents of a file before it is passed
Xto one of the existing language scanners. It is typically
Xused in conjunction with the plain text scanner.
XThe first <lang> defines a new language, the second <lang>
Xspecifies an existing language whose scanner will be used,
Xand the remaining <filter> is an arbitrary shell command.
X.PP
XYou may get a brief summary of the scanner-specific options for a
Xlanguage by supplying the following option: `-S<language>?'.
X.PP
XHere is a brief summary of the options for the
X.I `asm'\^
X(assembler) language.
X.PP
XThe
X.B \-u\^
Xoption controls whether or not the assembler scanner should strip
Xoff a leading
X.I underscore\^
X(`_') character.  If your assembler prepends an
X.I underscore\^
Xto external symbols, then you should tell the scanner to strip it
Xoff, so that references to the same symbol from assembly and from
Xa high-level language will look the same.
X.PP
XThe
X.B \-c<cc>\^
Xoption supplies the character(s) used to begin a comment that extends
Xto the end of the line.
X.PP
XThe
X.B \-a<cc>\^
Xoption indicates character(s) that are legal in names, in addition to
Xthe alpha-numeric characters.  If the option appears as `-a', names
Xthat contain these characters are ignored.  If it appears as `+a', these
Xnames are added to the database.
X.SH BUGS
XThis manual page needs to be more complete about the scanner-specific
Xarguments.
X.PP
XAt the moment, the only scanners implemented are for C, assembly
Xlanguage, and plain text.  There ought to be scanners for Ada, Pascal,
XFortran, and Lisp.
X.SH SEE ALSO
Xlid(1), deroff(1), detex(1).
END_OF_FILE
if test 5564 -ne `wc -c <'mkid.1'`; then
    echo shar: \"'mkid.1'\" unpacked with wrong size!
fi
# end of 'mkid.1'
fi
echo shar: End of archive 4 \(of 11\).
cp /dev/null ark4isdone
MISSING=""
for I in 1 2 3 4 5 6 7 8 9 10 11 ; do
    if test ! -f ark${I}isdone ; then
	MISSING="${MISSING} ${I}"
    fi
done
if test "${MISSING}" = "" ; then
    echo You have unpacked all 11 archives.
    rm -f ark[1-9]isdone ark[1-9][0-9]isdone
else
    echo You still need to unpack the following archives:
    echo "        " ${MISSING}
fi
##  End of shell archive.
exit 0
--
======================================================================
domain: tahorsley@csd.harris.com       USMail: Tom Horsley
  uucp: ...!uunet!hcx1!tahorsley               511 Kingbird Circle
                                               Delray Beach, FL  33444
+==== Censorship is the only form of Obscenity ======================+
|     (Wait, I forgot government tobacco subsidies...)               |
+====================================================================+