CREF - general purpose cross-reference generator.

Syntax:

cref [infile] [options]* [>outfile]

+B                       +C
Directive=file           indeX=indexfile
lineWidth=nn (80)        (+|-)Listing (+)
+Pascal

Examples:

cref /prog1 +b >listing
cref /wrog1 w=132 d=userfile >stuff
cref x=manyfiles +pasc

Options:

infile: is a file containing the source for cross-referencing.
outfile: is the file to which output is sent. If ">outfile" is not specified, output is sent to the terminal.
indeX=indexfile: specifies a file that contains the names of several files, all of which contain source for cross-referencing. "indexfile" has one file name per line.
Directive=file: specifies a file containing source code directives. The words in this file are taken to be keywords in the programming language that is being examined; thus CREF will not generate reference indices for these words. CREF has pre-defined directive files for the programming languages B, C, and Pascal.
+B: indicates that the source file(s) contain B source code.
+C: indicates that the source file(s) contain C source code.
+Pascal: indicates that the source file(s) contain Pascal source code.
lineWidth=nn: specifies a maximum output linewidth of "nn" columns. "nn" must be between 50 and 132 (inclusive). Values specified outside this range will be ignored and the width will be set to the closest limit. The default width is 80.
-Listing: tells CREF to generate only a cross-reference map. Normally CREF generates a line-numbered source listing as well as the cross-reference map.

Description:

Given a file of directives and a file of source or text, CREF produces a line-numbered listing of the source and a cross-reference map. The map is in dictionary order and contains all variables, function names, literals, strings, and comments.

CREF will not produce map entries for any words found in specified directive files. The options +B, +C, and +Pascal instruct CREF to access pre-defined directive files containing the keywords of the B, C, and Pascal programming languages (respectively). The user may produce his or her own directive file to specify any other keywords CREF should ignore.

Sequences of characters more than 40 characters long will be truncated to 40 characters for output purposes; no warning is given when this occurs.

If "infile" and "indeX=" are both specified, CREF will begin by processing "infile" and then continue with the files listed in the index file. If one of +B, +C, or +Pascal is specified, the "Directive=" option may not be specified also; if this happens, an error message is issued and CREF terminates.

Known Bugs:

This program will not work well with field-oriented source like assembler. It will not recognize comments that are indicated by a keyword (e.g. Basic's REM or Algol's COMMENT), nor will it recognize comments indicated by a character in a specific column (e.g. Fortran's "C" in column one). In such cases, CREF will continue merrily along cross-referencing each word in the comment. This may lengthen the map slightly but doesn't prevent the use of the program with these languages.

CREF may give strange results if the directive file is not properly set up. Extreme care must be taken when specifying SKIPSTR and STOPSTR (see the following section).

Directive files:

The directive file provides the cross-referencer with the information it needs to identify various tokens in the input source. The file may include the following entries.

SKIPSTR="string": specifies a string in double quotes containing all of the characters which may be skipped before reaching the start of a token. It must not contain any characters which are valid in a token nor the first character of a string in the Begin option of a SEQuence directive. White space characters (blanks, tabs, and new-lines) are automatically included in SKIPSTR because some of them cannot be entered directly.
STOPSTR="string": specifies a string in double quotes containing all the characters on which the scan should stop. This is usually the same as SKIPSTR except that STOPSTR should contain the first characters of the strings in the Begin option of a SEQuence directive.
SEQuence Begin="string" Finish="string" +esc | -esc: This line provides information about recognizing comments, literals, and strings. Begin= specifies a string which starts a comment, literal, or string. Finish= specifies a string which terminates a comment, literal, or string. +esc indicates that escape characters are to be recognized in the string. -esc indicates that escape characters can be ignored in the string.
ESCHAR=char: specifies an escape character or sequence.
KYword: indicates that the line contains words to be added to the list of keywords that should be ignored when preparing the cross-reference map.
IGNORE="string": specifies a character sequence which should be ignored if it is found in a string or literal. This might include such things as Pascal's "" to indicate a " in a string. An escape character followed by a quote is automatically ignored.

As an example of the directive file format, we give the B language directive file below.

skipstr="!#$%&()=-~^|\{}[]`@**:;?><,+"
stopstr="!*"#$%&'()=-~^|\{}[]`@**:;/?><,+"
seq b="'" f="'" +esc
seq b="`" f="`" +esc
seq b='"' f='"' +esc
seq b="/*" f="*/" -esc
eschar="*"
ky auto break case default do else extrn for
ky return switch while goto if next repeat