FILE NAME: read.me
CPP Version 5.3 for the IBM PC
February 1, 1990


REWARD

A reward of $5.12 is cheerfully paid to the first person who finds any bug in
this code. Typo's in the code or in the documentation are worth $1.28.


AUTHOR

All programs on this disk were written by:

Edward K. Ream
1617 Monroe Street
Madison, WI 53711
(608) 257-0802


PUBLIC DOMAIN SOFTWARE

The sole author and owner of CPP, Edward K. Ream, hereby places CPP and
all other files on this disk in the public domain.


DISCLAIMER

With respect to the programs and documentation contained on this disk,
Edward K. Ream specifically disclaims all warranties, express or implied,
including but not limited to implied warranties of merchantability and fitness
for a particular purpose. In no event shall Ream be liable for any loss of
profit or commercial damage, including but not limited to special, incidental,
consequential or other damages.


FILES ON DISK 1

read.meThis file.
cpp.docDocumentation for CPP.

cpp*.hHeader files for CPP.
cpp*.cSource code files for CPP.
cpp.exeExecutable version of CPP.

cpp.makTurboc C make file for cpp.exe.
cpp.lnkTurboc C link file for cpp.exe.
mcpp.mmkMicrosoft C make files for cpp.exe.
cpp.mlMicrosoft C link files for cpp.exe.


FILES ON DISK 2

read.me2Brief summary of Sherlock system.
sherlock.docDocumentation for the Sherlock (TM) debugging system.
dummysl.hDummy macro definitions for all Sherlock macros.
cppdb.exeExecutable version of CPP, withSherlock macros added.
See the source code listing for the names of tracepoints.
Add ++dump to the command line for a listing of statistics.
All sherlock output goes to standard out.
cppdbx.exeSame as cppdb.exe except that timing statistics are disabled.

cppdb.makTurboc C make file for cppdb.exe.
cppdb.lnkTurboc C link file for cppdb.exe.
mcppdb.mmkMicrosoft C make file for cppdb.exe.
cppdb.mlMicrosoft C link file for cppdb.exe.

macro.tstHairy tests of macro expansion from the draft standard.

Note:Turbo C make and line files are for version 2.0 or later.
Microsoft C make and link files are for version 5.0x or later.


KNOWN PROBLEMS

1. The draft ANSI C standard specifies that macros which take arguments are to be
considered "identical" only if the spellings of all formal parameters are
identical and the respective replacement texts are identical. For example, the
the following two #defines are NOT supposed to be considered identical and a
warning is supposed to be given,

#define max(a,b) (( (a) > (b) ) ? (a) : (b))
#define max(A,B) (( (A) > (B) ) ? (A) : (B))

SPP considers two macros to be identical if their replacement text are
identical. SPP does not check the actual spellings of formal parameters to
macros. This additional checking is left as an exercise to the reader.

SPP does check the placement of parameters within the replacement text, so that
a warning about a non-identical redefinition is issued in the following
example,

#define max(a,b) (( (a) > (b) ) ? (a) : (b))
#define max(a,b) (( (b) > (a) ) ? (a) : (b)) /* oops */

2. Version 5.3 supports single-line comments, which start with // and continue
to the end of the line. Naturally, the // character sequence does not start a
single-line comment if it occurs inside a normal comment or a string.

Single line comments are treated EXACTLY like regular C comments. In
particular, this means that single line comments are replaced by a single blank
in the replacement text of macros.

You C++ language experts will recognize that current C++ compilers handle
single-line comments as explained above, and that anachronistic C++ translators
included // (and any text following //) in the replacement text of macros.


COMPILER WARNINGS YOU MAY SAFELY IGNORE

def.c: When using the Turbo C compiler and when Sherlock macros are disabled
there are two warnings about variables not being used. These warnings go away
if Sherlock macros are defined.

utl.c: When using the Turbo C compiler there are five warnings about
"Possibly incorrect assignments."


BUGS FIXED IN VERSION 5.1

o White space was not allowed in the list of formal arguments to a macro. The
fix was mad to pp_def() in DEF.C.

o Token pasting did not work properly because white space was inserted between
tokens. The fix was made to pp_def().

o Stringizing did not affect character constants, only strings. The fix was
made to substitute() in DEF.C.


BUGS FIXED IN VERSION 5.2

o Comments were not allowed everywhere in preprocessor directives.
The fix was to do_pp() in DIR.C.

o CPP looped when skipping some kinds of comments. The fixes were in
skip_pp() and copy_pp() in UTL.C.

o Backslash-newline combinations were not properly deleted by sysnext().
CPP now follows the Draft ANSI Standard, which means that you can put the
backslash-newline combination absolutely ANYWHERE, inside identifiers,
keywords, multi-character operators, etc.


BUGS FIXED IN VERSION 5.3

o An extra carriage return was inserted at the end of each line.

o Very long or deeply nested macro expansions caused CPP to crash due to stack
overflow. It is still possible to crash the stack, but it's much less likely.
Fixes were made to substitute(), expand() and rescan() in DEF.C.