{Begin SubSec Indexing and Cross Referencing Files}
{Title Indexing and Cross Referencing Files}
{Text



{Begin SubSec SINGLEFILEINDEX}
{Title SINGLEFILEINDEX}
{Text

{index *BEGIN* SINGLEFILEINDEX package}


{note SINGLEFILEINDEX was written by M. D. Yonke.}


{it
Note:  SINGLEFILEINDEX is a LispUsers package that is contained on the file {lisp SINGLEFILEINDEX.DCOM}.
}


SINGLEFILEINDEX is a package for giving the user an alphabetical function index on the front of each lisp file listed by Interlisp.  This package is similar to the MULTIFILEINDEX package described below, except that SINGLEFILEINDEX provides a table of contents for functions only, and operates on one file at a time.  However, SINGLEFILEINDEX is much simpler and faster than MULTIFILEINDEX and is useful every time a file is made.


The first page gives the filename, time of creation, and the time of the listing.  Following that (on possibly more than one page) are {arg N} columns of function names and index numbers, where the index number indicates the function's linear occurrence within the file.  The number of columns is determined by the length of the longest function name, as well as by the number of functions in the file as described below.  The file is then printed with the filename and page number at the top of every page, and each function is preceded by its index number right-justified on the page.


When the SINGLEFILEINDEX package is first loaded, it redefines {fn LISTFILES1} ({PageRef Fn LISTFILES1}) so that all files listed by {fn LISTFILES} will be listed by calling {lisp (SINGLEFILEINDEX {arg FILE} NIL NIL)}.  Note that the file being indexed does not have to be loaded, or even noticed in the file package sense.



{FnDef {FnName SINGLEFILEINDEX} {FnArgs FILE OUTPUTFILE NEWPAGEFLG}
{Text
{arg FILE}  is the lisp source file.  {arg OUTPUTFILE} is the destination file.  If {arg OUTPUTFILE}={lisp NIL}, then the value of {var PRINTER}{index PRINTER Var} (initially {lisp LPT:}) is used.  {arg NEWPAGEFLG}={lisp T} means each function will be printed on a new page.  The value of {var FILELINELENGTH} determines the position of the index numbers, as well as  the placement of the columns.  The value of {var LINESPERPAGE} (initially 58) determines the number of lines per page.
}}


{index *END* SINGLEFILEINDEX package}

}{End SubSec SINGLEFILEINDEX}





{Begin SubSec MULTIFILEINDEX}
{Title MULTIFILEINDEX}
{Text

{index *BEGIN* MULTIFILEINDEX package}


{note MULTIFILEINDEX was written by J. J. Vittal.}


{it
Note:  MULTIFILEINDEX is a LispUsers package that is contained on the file {lisp MULTIFILEINDEX.DCOM}.
}



Many systems built in Interlisp consist of a number of symbolic source files. Finding one's way around in the listings can often be very tedious, even for the implementor of the system, if you don't know the system and the structure of the files intimately.  The MULTIFILEINDEX package is an attempt to help users deal with this problem by creating a listing of an entire system or set of files, including an alphabetized table of contents containing entries for each function on any of the files.  Information (but not unique index numbers) is included for other entities in the files such as records, blocks, and properties.  The function {fn MULTIFILEINDEX} implements this mechanism.


{FnDef {FnName MULTIFILEINDEX} {FnArgs SOURCEFILES DESTINATIONFILE NEWPAGEFLG}
{Text
{arg SOURCEFILES} is a list of file names (if atomic, {lisp (LIST {arg SOURCEFILES})} is used).  If it is {lisp NIL}, {fn MULTIFILEINDEX} returns immediately.  If it is {lisp T}, the value of {var FILELST} is used ({PageRef Var FILELST}).  {arg DESTINATIONFILE} is the output file.  If {arg DESTINATIONFILE} is {lisp NIL}, the value of {var PRINTER} is used (below).  If {arg NEWPAGEFLG}={lisp T},  each function in the listing will be placed on a page by itself.
}}



In the default case, {fn MULTIFILEINDEX} does the following:

(1)  Outputs an alphabetized table of contents (index) indicating the name of an object (function, record, block, variable, and so on), the file that it belongs to, and its type (property, variable (set or saved), record, block, and so forth).  If the object is the name of a function, then the information includes a unique index in the listing for the function, its type ({lisp EXPR}, {lisp FEXPR*}, etc.), and its argument list.  Note that it handles functions/files that use DECL ({PageRef Tag DECL}).  Otherwise, the index represents the index of the function immediately preceeding the definition of the entity.  

(2)  Outputs a listing of the files with each function being preceeded by its index number right-justified on the line.  Header information is placed at the top of each page, and the pages are numbered.

(3)  Undoably removes the names of the files indexed from {var NOTLISTEDFILES}{index NOTLISTEDFILES Var} ({PageRef Var NOTLISTEDFILES}).




{fn MULTIFILEINDEX} is effected by the following variables:


{VarDef {Name MULTIFILEINDEXMAPFLG}
{Text
If {lisp T}, indicates that you want the file index output.  Initially {lisp T}.
}}


{VarDef {Name MULTIFILEINDEXFILESFLG}
{Text
If {lisp T}, indicates that you want the file listings output to {arg DESTINATIONFILE}.  Initially {lisp T}.
}}


{VarDef {Name PRINTER}
{Text
If the {arg MAPFILE} argument to {fn MULTIFILEINDEX} is {lisp NIL}, it defaults to the value of {var PRINTER}.  Initially {lisp {bracket LPT}} in Interlisp-D, {lisp LPT:} in Interlisp-10.
}}


{VarDef {Name LINESPERPAGE}
{Text
The value of {var LINESPERPAGE} determines the number of lines per page.  Initially 65 in Interlisp-D, 58 in Interlisp-10.
}}


{VarDef {Name FONTCHANGEFLG}
{Text
If {lisp NIL}, page headings and the index numbers that preceed the definition of each function are printed bold; that is, overprinted; otherwise, they are printed using the {lisp BOLDFONT} ({lisp PRETTYCOMFONT} if {lisp BOLDFONT} doesn't exist) in the current {var FONTPROFILE} (see {PageRef Tag FontProfile}).  
}}


{VarDef {Name FILELINELENGTH}
{Text
The value of {var FILELINELENGTH} determines the width of the page.
}}


The following four parameters affect how the columns are placed:

{VarDef {Name MULTIFILEINDEXCOLS} }
{VarDef {Name MULTIFILEINDEXNAMECOL} }
{VarDef {Name MULTIFILEINDEXFILECOL} }
{VarDef {Name MULTIFILEINDEXTYPECOL}
{Text
The value of {var MULTIFILEINDEXCOLS} indicates how the other three are to be interpreted.  If {var MULTIFILEINDEXCOLS} is the atom {lisp FLOATCOLS} (its initial value), then an attempt is made to fit the columns onto the page in a way that maximizes the amount of space for the type information (the amount of space allocated for the type field must be at least 45% of {var FILELINELENGTH} in this case).  If {var MULTIFILEINDEXCOLS} is either {lisp T} or {lisp FIXCOLS}, then the value of the other variables are treated as absolute column positions on the page.  If {var MULTIFILEINDEXCOLS} is either {lisp NIL} or {lisp FIXFLOATCOLS}, the columns will be floated, but will not be any smaller than the column positions defined by the other variables.

The initial values of these four variables are {lisp FLOATCOLS}, 0, 26 and 41, respectively.
}}



{fn MULTIFILEINDEX} has an interface to Masterscope.  If the value of either of the next two variables is {lisp T}, then {fn MULTIFILEINDEX} assumes that the sourcefiles have already been analyzed by Masterscope, and calls {fn UPDATECHANGED}.  

{VarDef {Name MULTIFILEINDEXFNSMSFLG}
{Text
If {lisp T}, indicates that you want the Masterscope information about each function output.  This includes who calls each function, who this function calls, and what variables are set or referred to either locally or freely.  Initially {lisp NIL}.
}}


{VarDef {Name MULTIFILEINDEXVARSMSFLG}
{Text
If {lisp T}, indicates that all variables used in the files should have some information output about them at the end of the listing.  The list of variables to look at is obtained by effectively asking Masterscope the question: "{lisp WHO IS USED BY ANY AND WHO IS SET BY ANY}".  The listing will include information about who binds, uses freely or locally, or smashes freely or locally each variable.  The variable map is case-independently sorted by the name of the variable.  Initially {lisp NIL}.
}}




In order to make the index, or map, of the files, the filecoms for all the files being listed need be loaded (see {PageRef Tag filecoms}); {fn MULTIFILEINDEX} does a {fn GETDEF} on each file (file names are obtained using {fn FINDFILE}) to obtain its filecoms.  As other indirections are noted, they also are obtained using {fn GETDEF}.  For example, if you have a file {lisp TEST}, and its filecoms is {lisp ((FNS * TESTFNS))}, just doing a {fn GETDEF} on {lisp TESTCOMS} will not suffice; as the expression {lisp (FNS * TESTFNS)} is parsed, a {fn GETDEF} is also done to obtain the value of {lisp TESTFNS}.



{VarDef {Name MULTIFILEINDEXLOADVARSFLG}
{Text
If {lisp T}, then a {fn LOADVARS} of all the {lisp VARS} on a particular file is performed before the filecoms is loaded with {fn GETDEF}.  Initially {lisp NIL}.
}}


{VarDef {Name MULTIFILEINDEXGETDEFFLG}
{Text
If {lisp T}, {fn MULTIFILEINDEX} will inform the user when it does {fn GETDEF}s.  Initially {lisp NIL}.
}}





{index *END* MULTIFILEINDEX package}

}{End SubSec MULTIFILEINDEX}



}{End SubSec Indexing and Cross Referencing Files}