Title: The Inform 7 compiler
Author: Graham Nelson

@ The task of the Inform 7 compiler is to take natural-language source text
and "transpile" it down to lower-level, more orthodox code which another
compiler can take the rest of the way. Usually, but not necessarily, that
other compiler is the typeless but otherwise C-like Inform 6 (1996-2003).

Inform offers three compiler tools: //inbuild//, //inform7// and //inter//,
though really they are three points of access to the same code base. //inbuild//
contains Stage 1 as a stand-alone tool, //inter// contains Stages 5 and 6 as
a stand-alone tool, and //inform7// is the entire compiler (Stages 1 to 6) in one.
See //inbuild: Manual//, //inform7: Manual//, //inter: Manual// and
//inbuild: Reference Card//, //inform7: Reference Card//, //inter: Reference Card//.

Each tool has its own CLI (or "command-line interface") but is otherwise
divided up into "modules", many shared between two or even all three tools.
= (hyperlinked text as BoxArt)
        INBUILD                  INFORM7                   INTER     
    +-------------+          +-------------+          +-------------+    
    |   //inbuild//   |          |   //inform7//   |          |    //inter//    |
    |    (cli)    |          |    (cli)    |          |    (cli)    |
    +-------------+          +-------------+          +-------------+    
      .         .              .         .              .         .  
+---------------------------+  .         .              .         .         
|  //supervisor//-module        |  .         .              .         .         } Stage 1
+------------------------+  +------------------+        .         .   
      .         .        |     //core//-module     |        .         .         } Stage 2
      .         .        | ------------------- |        .         .  
      .         .        |  //assertions//-module  |        .         .         }
      .         .        |    //values//-module    |        .         .         } Stage 3
      .         .        |   //knowledge//-module  |        .         .         }
      .         .        |      //if//-module*     |        .         .         } * not used in
      .         .        |  //multimedia//-module* |        .         .         } Basic Inform
      .         .        | ------------------- |        .         .  
      .         .        |  //imperative//-module  |        .         .         } Stage 4
      .         .        |    //runtime//-module   |        .         .         } 
      .         .        +------------------+  +------------------------+
      .         .              .         .  |         //bytecode//-module   |   }
      .         .              .         .  |         //building//-module   |   } Stage 5
      .         .              .         .  |         //codegen//-module    |   }
      .         .              .         .  | ------------------------- |
      .         .              .         .  |         //index//-module      |   } Stage 6
      .         .              .         .  +---------------------------+
      .         .              .         .              .         .  
+-----------------------------------------------------------------------+
|  SERVICES              shared //linguistics//-module                      |
|                         shared //calculus//-module                        |
|                          shared //kinds//-module                          |
|                         shared //lexicon//-module                         |
|                        shared //inflections//-module                      |
|                         shared //problems//-module                        |
|                          shared //syntax//-module                         |
|                          shared //words//-module                          |
|                           shared //arch//-module                          |
|                           shared //html//-module                          |
+-----------------------------------------------------------------------+
      .         .              .         .              .         .  
+-----------------------------------------------------------------------+
|  FOUNDATION      //foundation//-module (in inweb repository)              |
|                   (Posix or Windows-related functions)                |
|                           (standard C library)                        |
+-----------------------------------------------------------------------+
=
The Inform compiler runs in six stages. It is not literally true that each
completes before the next begins, but compilation broadly flows diagonally
downwards and rightwards in the diagram:
(*) Stage 1. The build manager //supervisor// decides what must be compiled.
(*) Stage 2. //core// organises compilation of a single Inform project,
doing little except to co-ordinate the other modules.
(*) Stage 3. //assertions//, //values// and //knowledge// assemble a world model
and a set of rules and phrases to operate it. //if// and //multimedia// provide
"plugins" with additional features, adapting the language for interactive fiction.
(*) Stage 4. //imperative// and //runtime// turn the constructs from Stage 2
into an intermediate bytecode format called Inter.
(*) Stage 5. //bytecode//, //building// and //codegen// optimise the Inter
code and translate it to our final output.
(*) Stage 6. //index// generates the human-readable Index pages, which are like
a small website about the project.

@ All three tools each use a "services" library, made up of a variety of modules
providing services useful for natural language-based programs. At one time this
was going to be called "Second Foundation" or possibly "Foundation and Empire",
because there is also //foundation// underneath, a library of utility functions
provided by //inweb//.

@ That's a lot: for code-spelunkers, this is a veritable limestone hillside.
Where to begin? Here are some suggested entrances:
(a) See //supervisor: What This Module Does// for an overview of the
build-management process.
(b) Or take that on trust, and see //core: What This Module Does// for
an overview of how Inform 7 basically works.
(c) If you're more interested in the low-level representation of Inter code,
and how to generate from it, see //bytecode: What This Module Does//.