=======================================================================
INFORM SYNTAX STYLING FOR WINDOWS 95/NT
Version 0.2   January 31st 1999    John G. Wood <john@elvw.demon.co.uk>
=======================================================================

This is a collection of sample C++ code for syntax styling Graham
Nelson's Inform.  In his original post, Graham referred to this as
syntax colouring; I have generalised "colour" to "style" since I allow
the use of italic and bold text as well as colour when presenting this.
The code is organised into packages, so you can use as little or as much
as you like - the various packages are described below.  If you just
want to see how it works in practice, run the sample application
InformViewer.exe and open an Inform source file (one is provided).

I hereby release this into the public domain; if you find it useful, I
would appreciate it if you could let me know.  A mention in the credits
would be nice too, but it's entirely up to you.

This is the second public release and it is very much alpha - any
reports of problems (other than those mentioned below) will be
gratefully received.  My thanks (of course) to Graham Nelson for doing
all the hard parts - coming up with the language, compiler, and
algorithm in the first place!

John


INFORM AND IF
-------------
If you don't know Inform, this will be completely useless to you.
Inform is a language for writing Interactive Fiction (IF, or "text
adventures") - for more information try one of the following:

	Inform homepage:    http://www.gnelson.demon.co.uk/inform.html
	Author's newsgroup: rec.arts.int-fiction
	IF archives:        ftp://ftp.gmd.de/if-archive/


THE FILES
---------
There are a few auxiliary files in this distribution:

        ReadMe.txt :    You're reading it!
        Algorithm.txt : Graham Nelson's original algorithm, together
                        with notes on how I've changed it.
        Sample.inf :    A sample file to get you going.

The rest of the files are source files or else files necessary to build
the sample application (InformViewer.exe, also included).  These fit
together as follows, with packages lower in the diagram depending on
those higher up.  Best in a non-proportional font:

            +-----------------------+
            | 0. STYLE DEFINITIONS  |
            |-----------------------|
            | InformStyle.h         |
            +-----------+-----------+
                        |                 Windows/MFC               
               +--------+-------+             |
               |                |             |      
 +-------------+-------+  +-----+-------------+-----+
 | 1. SYNTAX STYLING   |  | 2. STYLE PRESENTATION   |
 |---------------------|  |-------------------------|
 | InformStyler.h,cpp  |  | InformStyleRecord.h,cpp |
 +-------------+-------+  +----+---------------+----+
               |               |               |     
               |               | +-------------+-------------+
               |               | | 2a. STYLE OPTIONS DIALOG  |
               |               | |---------------------------|
               |               | | InformStyleDlg.h,cpp  *   |
               |               | +-------------+-------------+
               |               |               |
          +----+---------------+----+          |
          | 3. STYLED EDIT CONTROL  |          |
          |-------------------------|          |
          | InformEditCtrl.h,cpp    |          |
          +-------------------+-----+          |
                              |                |
                         +----+----------------+----+
                         | 4. SAMPLE APPLICATION    |
                         |--------------------------|
                         | BusyCursor.h             |
                         | InformViewer.h,cpp,...   |
                         | InformViewerDoc.h,cpp    |
                         | InformViewerView.h,cpp   |
                         | MainFrm.h,cpp            |
                         | Resource.h               |
                         | StdAfx.h,cpp             |
                         | res/InformViewer.ico,rc2 |
                         | res/InformViewerDoc.ico  |
                         | res/Toolbar.bmp          |
                         +--------------------------+

* But see also InformViewer.rc and resource.h for dialog resources.


THE PACKAGES
------------

0. Style Definitions
--------------------
"InformStyle.h" simple contains an enumeration of the possible syntax
styles (Foreground, Quoted Text, etc) from GN's algorithm.

I have added two new styles, Number and CodeNumber, for my own benefit.
These are used for constant integers (decimal, hexadecimal or binary) in
declarations and in code respectively.

1. Syntax Styling
-----------------
The InformStyler class encapsulates the state machine from GN's
algorithm (modified as described in "Algorithm.txt").  Its only
significant public method is ColourString(), which builds up a map of
styles for a given text string.

ColourString() is not optimised for speed, but it takes less than a
second on my P166 to process a 4400+ line Inform file one line at a
time.

Note that this code requires neither Windows nor MFC (although you would
have to dummy a few type definitions such as LPCTSTR to use it in
another environment).

2. Style Presentation
---------------------
The InformStyleRecord class contains the visual representation
information for one style - colour, bold and italic - plus a text name
for the benefit of the style options dialog.  The InformStyle enum entry
is referred to as the record's ID.

Also defined is a mapping class InformStyleRecordSet from IDs to
records.  There is a global object of this type accessible via
GetMasterStyles().

2a. Style Options Dialog
------------------------
The CInformStyleDlg class is simply a dialog box which allows the user
to customise the style presentation.  Pass it an InformStyleRecordSet on
construction and it will do the rest.  See "InformViewer.cpp" for an
example of using this.

Note that this requires the dialog resources from the sample application
- it should be easy enough to copy them across.

3. Styled Edit Control
----------------------
The CInformEditCtrl class is derived from a rich edit control.  It
currently has one interesting method, SetText().  This sets the text of
the control then colours it using an Inform syntax styler and the
master style set.  To ease styling when the text is edited, I store the
style's state for the start of each line.

This is the least satisfactory package.  In version 0.1 the 4400+ line
Inform file mentioned above took over TWO MINUTES to prepare on my P166;
it now takes less than three seconds, but in order to do this I have had
to produce RTF codes by hand, which has made the code quite messy.

The other problem is that I have only implemented it as a viewer.  If
the text is edited it will be wrongly styled unless the whole text is
processed again.

I hope to do something about both these problems in future releases but
thought it was worth releasing in it's current state anyway.

4. Sample Application
---------------------
InformViewer.exe is a simple SDI application that allows you to view
syntax-styled Inform files.  CInformViewerDoc just reads files into a
CString accessible to its views; CInformViewerView maintains a styled
edit control filling it's client area and updates the text when
necessary.  CInformViewerApp does three things of interest:
  a. It loads the master styles from the registry (if preferences have
     been written into the registry) in InitInstance();
  b. It saves the master styles to the registry in ExitInstance();
  c. It handles the "Tools|Syntax styles" command, updating all views
     in all documents if the styles have changed.


