infocom/compilers/inform5/utilities/infact.notes

                The Inform debugging information format
                =======================================

  One option when compiling with Inform is to generate a file of debugging
information, which may be used in conjunction with the object code (the
story file) by a run-time debugger (a special kind of game interpreter with
tracing and debugging feature).  The utility Infact can be used to get a
print-out of some or all of the information in this file.  A prototype
debugger, Infix, is currently being tested.

  The debugging file is a list of "lines", which occur in no guaranteed
order: a single byte gives the line type, and the rest of the format depends
on what it is.

   Type                          Format

   0      (marks end of file)
   1      File                   <number>  <include-name>  <expanded-name>
   2      Class                  <start-line>  <name>  <end-line>
   3      Object                 <2-byte-number>
                                    <start-line>  <name>  <end-line>
   4      Global                 <number>  <name>
   5      Attribute              <number>  <name>
   6      Property               <number>  <name>
   7      Fake action            <number>  <name>
   8      Action                 <number>  <name>
   9      Header                 <64 bytes of data>
   10     Code line              <line>  <address>
   11     Routine starts         <2-byte number>  <start-line>
                                 <name> [<var1-name>... ]  0
   12     Codeless line          <line>
   13     Memory map             <dictionary-start-address> <dict-end>
                                 <code-start> <code-end>
                                 <strings-start> <strings-end>
   14     Routine ends           <2-byte number>  <end-line>
   15     Source code ref        <line-num> <3-byte address in its file>
   16     File size              <file-number> <3-byte number of chars read>

  Here a <line> is always in the form <file number> <2-byte line number>
(the two bytes stored high-then-low); <names> are all null terminated; and a
Z-code <address> is a byte address stored in three bytes, high to low.  All
<number>s are single-byte except where stated.

  The header is the block of 64 bytes at the front of a "story file"
(i.e. Infocom game file).  The point of this is that the debugger should
only allow itself to be used when these 64 bytes agree with the first
64 of the game being played under it.  This pretty much guarantees that
the story file was compiled in the same run as the debugging information
file.

  Files are numbered from 1 in order of first opening.

  Globals are numbered 0 to (potentially) 239.

  Objects are numbered from 1 upwards (0 is a null value), and there can
certainly be more than 255.

  Because of "aliasing" (i.e. a vile but necessary form of doubling-up)
one may expect several attributes/properties to have the same number as
each other.

  Source code references are generated about every 16 lines to enable
a program to find a given line number in the source code quickly
(without searching through and counting new-lines).

                                                      September 1994