Address more of the TODO items.

[ibg.git] / chapters / 14.rst

diff --git a/chapters/14.rst b/chapters/14.rst
index 0b99b449c05ca7a95e2c796c266ed37c7e812683..e9f2a8da31c935556c1c0f437a4d52076713a1fc 100644 (file)
--- a/chapters/14.rst
+++ b/chapters/14.rst
@@ -11,18 +11,14 @@
   .. image:: /images/picF.png
      :align: left
 
   .. image:: /images/picF.png
      :align: left
 

-.. raw:: latex
-
-   \dropcap{f}
-
-inally our three example games are written; we've shown you as much of 
-the Inform language as we've needed to, and made a lot of observations 
-about how and why something should be done. Despite all that, there's 
-much that we've left unsaid, or touched on only lightly. In this chapter 
-we'll revisit key topics and review some of the more significant 
-omissions, to give you a better feel for what's important, and what can 
-be ignored for the time being; when you become an accomplished designer, 
-you will decide what matters and what can be left on the shelf.
+|F|\inally our three example games are written; we've shown you as much of
+the Inform language as we've needed to, and made a lot of observations
+about how and why something should be done. Despite all that, there's much
+that we've left unsaid, or touched on only lightly. In this chapter we'll
+revisit key topics and review some of the more significant omissions, to
+give you a better feel for what's important, and what can be ignored for
+the time being; when you become an accomplished designer, you will decide
+what matters and what can be left on the shelf.

 
 We'll also talk, in :ref:`reading-other-code`, about a few ways of doing
 things that we've chosen not to tell you about, but which you're quite
 
 We'll also talk, in :ref:`reading-other-code`, about a few ways of doing
 things that we've chosen not to tell you about, but which you're quite


@@ -89,93 +85,89 @@ player), and we use the placeholders `{obj_id}`, `{var_id}`,
 Statements
 ==========
 
 Statements
 ==========
 

-.. todo::
-
-   We might need some custom syntax highlighting here.
-

 A :term:`statement` is an instruction intended for the interpreter, telling
 it what to do at run-time. It *must* be given in lower-case, and always
 ends with a semicolon.
 
 Some statements, like ``if``, control one or more other statements. We 
 use the placeholder `{statement_block}` to represent either a single 
 A :term:`statement` is an instruction intended for the interpreter, telling
 it what to do at run-time. It *must* be given in lower-case, and always
 ends with a semicolon.
 
 Some statements, like ``if``, control one or more other statements. We 
 use the placeholder `{statement_block}` to represent either a single 

-`{statement}`, or any number of `{statements}` enclosed in braces::
+`{statement}`, or any number of `{statements}` enclosed in braces:

 
 

-  statement;
-
-  { statement; statement; ... statement; }
+  | `{statement};`
+  |
+  | `{statement}; {statement}; ... {statement};`

 
 Statements that we've met
 -------------------------
 
 Our games have used these statements, about half of the Inform 
 
 Statements that we've met
 -------------------------
 
 Our games have used these statements, about half of the Inform 

-possibilities::
-
-  give obj_id attribute;
-  give obj_id attribute attribute ... attribute;
-
-  if (expression) statement_block
-  if (expression) statement_block else statement_block
-
-  move obj_id to parent_obj_id;
-
-  objectloop (var_id) statement_block
-
-  print value;
-  print value, value, ... value;
-
-  print_ret value;
-  print_ret value, value, ... value;
-
-  remove obj_id;
-
-  return false;
-  return true;
-
-  style underline; print...; style roman;
-
-  switch (expression) {
-      value: statement; statement; ... statement;
-      ...
-      default: statement; statement; ... statement;
-  }
-
-  "string";
-  "string", value, ... value;
-
-  <action>;
-  <action noun>;
-  <action noun second>;
-
-  <<action>>;
-  <<action noun>>;
-  <<action noun second>>;
+possibilities:
+
+  | `give {obj_id} {attribute};`
+  | `give {obj_id} {attribute} {attribute} ... {attribute};`
+  |
+  | `if ({expression}) {statement_block}`
+  | `if ({expression}) {statement_block} else {statement_block}`
+  |
+  | `move {obj_id} to {parent_obj_id};`
+  |
+  | `objectloop ({var_id}) {statement_block}`
+  |
+  | `print {value};`
+  | `print {value}, {value}, ... {value};`
+  |
+  | `print_ret {value};`
+  | `print_ret {value}, {value}, ... {value};`
+  |
+  | `remove {obj_id};`
+  |
+  | `return false;`
+  | `return true;`
+  |
+  | `style underline; print...; style roman;`
+  |
+  | `switch ({expression}) {`
+  |     `{value}: {statement}; {statement}; ... {statement};`
+  |     `...`
+  |     `default: {statement}; {statement}; ... {statement};`
+  | `}`
+  |
+  | `"{string}";`
+  | `"{string}", {value}, ... {value};`
+  |
+  | `<{action}>;`
+  | `<{action} {noun}>;`
+  | `<{action} {noun} {second}>;`
+  |
+  | `<<{action}>>;`
+  | `<<{action} {noun}>>;`
+  | `<<{action} {noun} {second}>>;`

 
 Statements that we've not met
 -----------------------------
 
 Although our example games haven't needed to use them, these looping
 
 Statements that we've not met
 -----------------------------
 
 Although our example games haven't needed to use them, these looping

-statements are sometimes useful::
-
-  break;
-  continue;
+statements are sometimes useful:

 
 

-  do statement_block until (expression)
-
-  for (set_var : loop_while_expression : update_var) statement_block
-
-  while (expression) statement_block
+  | `break;`
+  | `continue;`
+  |
+  | `do {statement_block} until ({expression})`
+  |
+  | `for ({set_var} : {loop_while_expression} : {update_var}) {statement_block}`
+  |
+  | `while ({expression}) {statement_block}`

 
 On the other hand, we suggest that you put the following statements on 
 hold for now; they're not immediately relevant to everyday code and have 
 
 On the other hand, we suggest that you put the following statements on 
 hold for now; they're not immediately relevant to everyday code and have 

-mostly to do with printing and formatting::
+mostly to do with printing and formatting:

 
 

-  box
-  font
-  jump
-  new_line
-  spaces
-  string
+  | `box`
+  | `font`
+  | `jump`
+  | `new_line`
+  | `spaces`
+  | `string`

 
 In particular, avoid using the deprecated jump statement if you possibly can.
 
 
 In particular, avoid using the deprecated jump statement if you possibly can.
 


@@ -310,8 +302,13 @@ two-state variables are attributes.
 Properties
 ----------
 
 Properties
 ----------
 

+.. Generated by autoindex
+.. index::
+   pair: before; library property
+   pair: name; library property
+

 The library defines around forty-eight standard property variables (such 
 The library defines around forty-eight standard property variables (such 

-as ``before`` or ``name``), but you can readily create further ones just 
+as :prop:`before` or :prop:`name`), but you can readily create further ones just 

 by using them within an object definition.
 
 You can create and initialise a property in an object's ``with`` segment:
 by using them within an object definition.
 
 You can create and initialise a property in an object's ``with`` segment:


@@ -370,6 +367,9 @@ and are usually called automatically by the library, or manually by::
 
   obj_id.property()                    ! everywhere
 
 
   obj_id.property()                    ! everywhere
 

+.. index::
+   single: arguments (of a routine)
+

 Arguments and local variables
 -----------------------------
 
 Arguments and local variables
 -----------------------------
 


@@ -409,11 +409,15 @@ or implicitly when the routine runs out of statements. If none of these
 
   [ routine_id; statement; statement; ... statement; ];
 
 
   [ routine_id; statement; statement; ... statement; ];
 

-returns ``true`` and ::
+.. Generated by autoindex
+.. index::
+   pair: true; library constant
+
+returns :const:`true` and ::

 
   property [; statement; statement; ... statement; ]
 
 
   property [; statement; statement; ... statement; ]
 

-return ``false``.
+return :const:`false`.

 
 This difference is *important*. Remember it by the letter pairs STEF: 
 left to themselves, Standalone routines return True, Embedded routines 
 
 This difference is *important*. Remember it by the letter pairs STEF: 
 left to themselves, Standalone routines return True, Embedded routines 


@@ -612,7 +616,7 @@ you'll come across.
     if (MyVar) ...
 
   Note that the following statement specifically tests whether ``MyVar`` 
     if (MyVar) ...
 
   Note that the following statement specifically tests whether ``MyVar`` 

-  contains ``true`` (1), *not* whether its value is anything other than 
+  contains :const:`true` (1), *not* whether its value is anything other than 

   zero. ::
 
     if (MyVar == true) ...
   zero. ::
 
     if (MyVar == true) ...


@@ -664,8 +668,13 @@ you'll come across.
 "number" property and "general" attribute
 -----------------------------------------
 
 "number" property and "general" attribute
 -----------------------------------------
 

-The library defines a standard ``number`` property and a standard 
-``general`` attribute, whose roles are undefined: they are 
+.. Generated by autoindex
+.. index::
+   pair: general; library attribute
+   pair: number; library property
+
+The library defines a standard :prop:`number` property and a standard 
+:attr:`general` attribute, whose roles are undefined: they are 

 general-purpose variables available within every object to designers as 
 and when they desire.
 
 general-purpose variables available within every object to designers as 
 and when they desire.
 


@@ -706,13 +715,17 @@ is virtually unlimited.
 Setting up the object tree
 --------------------------
 
 Setting up the object tree
 --------------------------
 

+.. Generated by autoindex
+.. index::
+   pair: found_in; library property
+

 Throughout this guide, we've defined the initial position of each object 
 within the overall object tree either by explicitly mentioning its 
 parent's ``obj_id`` (if any) in the first line of the object definition 
 -- what we've been calling the header information -- or, for a few 
 objects which crop up in more than one place, by using their 
 Throughout this guide, we've defined the initial position of each object 
 within the overall object tree either by explicitly mentioning its 
 parent's ``obj_id`` (if any) in the first line of the object definition 
 -- what we've been calling the header information -- or, for a few 
 objects which crop up in more than one place, by using their 

-``found_in`` properties. For example, in "William Tell" we defined 
-twenty-seven objects; omitting those which used ``found_in`` to define 
+:prop:`found_in` properties. For example, in "William Tell" we defined 
+twenty-seven objects; omitting those which used :prop:`found_in` to define 

 their placement at the start of the game, we're left with object 
 definitions starting like this::
 
 their placement at the start of the game, we're left with object 
 definitions starting like this::