projects / ibg.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
Tick some things off the TODO list.
[ibg.git] / appendices / f.rst
diff --git a/appendices/f.rst b/appendices/f.rst
index db6f55d3751f4c4b18c0cbb26f87e181b6eed238..0dc8e6449ad13efb9fd199a12cd4f0843316d8ff 100644 (file)
--- a/appendices/f.rst
+++ b/appendices/f.rst
@@ -2,6 +2,10 @@
  Appendix F -- Inform library
 ==============================
 
  Appendix F -- Inform library
 ==============================
 
+.. |ADD| replace:: **+**
+
+.. The ⊕ symbol doesn't work in LaTeX.
+
 .. default-role:: samp
 
 .. only:: html
 .. default-role:: samp
 
 .. only:: html
@@ -9,11 +13,7 @@
    .. image:: /images/picL.png
       :align: left
 
    .. image:: /images/picL.png
       :align: left
 
-.. raw:: latex
-
-   \dropcap{l}
-
-ibrary files define Inform's model world, turning a conventional
+|L|\ibrary files define Inform's model world, turning a conventional
 programming language into a text adventure development system.  Here are
 the library constants, variables and routines, the standard object
 properties and attributes, the verb grammars and actions.
 programming language into a text adventure development system.  Here are
 the library constants, variables and routines, the standard object
 properties and attributes, the verb grammars and actions.
@@ -29,18 +29,18 @@ Library objects
   If defined (between Includes of `Parser` and `VerbLib`), changes standard
   library messages:
 
   If defined (between Includes of `Parser` and `VerbLib`), changes standard
   library messages:
 
-    | `Object LibraryMessages`
-    |   `with before [;`
-    |        `{action}: "{string}";`
-    |        `{action}: "{string}";`
-    |        `{action}: switch (lm_n) {`
-    |                `{value}: "{string}";`
-    |                `{value}: "{string}",`
-    |                    `(a) lm_o,".";`
-    |                `...`
-    |                `}`
-    |            `...`
-    |        `];`
+  | `Object LibraryMessages`
+  |   `with before [;`
+  |        `{action}: "{string}";`
+  |        `{action}: "{string}";`
+  |        `{action}: switch (lm_n) {`
+  |                `{value}: "{string}";`
+  |                `{value}: "{string}",`
+  |                    `(a) lm_o,".";`
+  |                `...`
+  |                `}`
+  |            `...`
+  |        `];`
 
 `selfobj`
   The default player object.  Avoid: use instead the `player` variable,
 
 `selfobj`
   The default player object.  Avoid: use instead the `player` variable,
@@ -144,7 +144,8 @@ Library variables
   Used by `invent` and `list_together` properties.
 
 `keep_silent`
   Used by `invent` and `list_together` properties.
 
 `keep_silent`
-  Normally `false`; `true` makes most group 2 actions silent.
+  Normally `false`; `true` makes most :ref:`group 2 actions
+  <group-2-actions>` silent.
 
 `location`
   The player's current room; unless that's dark, when it contains
 
 `location`
   The player's current room; unless that's dark, when it contains
@@ -187,6 +188,8 @@ Library variables
 `wn`
   The input stream word number, counting from 1.
 
 `wn`
   The input stream word number, counting from 1.
 
+.. _library-routines:
+
 Library routines
 ================
 
 Library routines
 ================
 
@@ -194,7 +197,8 @@ Library routines
   A scored task has been achieved.
 
 `AfterRoutines()`
   A scored task has been achieved.
 
 `AfterRoutines()`
-  In a group 2 action, controls output of "after" messages.
+  In a :ref:`group 2 action <group-2-actions>`, controls output of "after"
+  messages.
 
 `AllowPushDir()`
   An object can be pushed from one location to another.
 
 `AllowPushDir()`
   An object can be pushed from one location to another.
@@ -216,17 +220,17 @@ Library routines
 `DrawStatusLine()`
   Refreshes the status line; happens anyway at end of each turn.
 
 `DrawStatusLine()`
   Refreshes the status line; happens anyway at end of each turn.
 
-`GetGNAOfObject(obj_id)`
+`GetGNAOfObject({obj_id})`
   Returns gender-number-animation 0..11 of the `{obj_id}`.
 
   Returns gender-number-animation 0..11 of the `{obj_id}`.
 
-`HasLightSource(obj_id)`
+`HasLightSource({obj_id})`
   Returns `true` if the `{obj_id}` has light.
 
 `IndirectlyContains({parnt_obj_id,obj_id})`
   Returns `true` if `{obj_id}` is currently a child or grand-child or
   great-grand-child... of the `{parent_object}`.
 
   Returns `true` if the `{obj_id}` has light.
 
 `IndirectlyContains({parnt_obj_id,obj_id})`
   Returns `true` if `{obj_id}` is currently a child or grand-child or
   great-grand-child... of the `{parent_object}`.
 
-`IsSeeThrough(obj_id)`
+`IsSeeThrough({obj_id})`
   Returns `true` if light can pass through the `{obj_id}`.
 
 `Locale({obj_id,"string1","string2"})`
   Returns `true` if light can pass through the `{obj_id}`.
 
 `Locale({obj_id,"string1","string2"})`
@@ -354,6 +358,8 @@ Library routines
   Returns the type of its `{arg}` : 3 for a string address, 2 for a routine
   address, 1 for an object number, or 0 otherwise.
 
   Returns the type of its `{arg}` : 3 for a string address, 2 for a routine
   address, 1 for an object number, or 0 otherwise.
 
+.. _object-props:
+
 Object properties
 =================
 
 Object properties
 =================
 
@@ -366,7 +372,7 @@ returns `true`):
   | `{property} [; {routine_id}(); ]`
   | `{property} {routine_id}`
 
   | `{property} [; {routine_id}(); ]`
   | `{property} {routine_id}`
 
-In this appendix, "⊕" marks an additive property.  Where a `Class` and an
+In this appendix, |ADD| marks an additive property.  Where a `Class` and an
 `Object` of that class both define the same property, the value specified
 for the `Object` normally overrides the value inherited from the `Class`.
 However, if the property is additive then both values apply, with the
 `Object` of that class both define the same property, the value specified
 for the `Object` normally overrides the value inherited from the `Class`.
 However, if the property is additive then both values apply, with the
@@ -377,7 +383,7 @@ Object's value being considered first.
   The `{value}` can be a space-separated list of `{obj_ids}`, or a routine
   which invokes `PlaceInScope()` or `ScopeWithin()` to specify objects.
 
   The `{value}` can be a space-separated list of `{obj_ids}`, or a routine
   which invokes `PlaceInScope()` or `ScopeWithin()` to specify objects.
 
-`after` ⊕
+`after` |ADD|
   For an object: receives every `{action}` and `{fake_action}` for which
   this is the `{noun}`.  For a room: receives every `{action}` which occurs
   here.
   For an object: receives every `{action}` and `{fake_action}` for which
   this is the `{noun}`.  For a room: receives every `{action}` which occurs
   here.
@@ -398,7 +404,7 @@ Object's value being considered first.
   For a non-English object: its definite and indefinite articles.  The
   `{value}` is an array of strings.
 
   For a non-English object: its definite and indefinite articles.  The
   `{value}` is an array of strings.
 
-`before` ⊕
+`before` |ADD|
   For an object: receives every `{action}` and `{fake_action}` for which
   this is the `{noun}`.  For a room: receives every action which occurs
   here.
   For an object: receives every `{action}` and `{fake_action}` for which
   this is the `{noun}`.  For a room: receives every action which occurs
   here.
@@ -435,7 +441,7 @@ Object's value being considered first.
   `StartDaemon({obj_id})` and which then runs once each turn until
   deactivated by `StopDaemon({obj_id})`.
 
   `StartDaemon({obj_id})` and which then runs once each turn until
   deactivated by `StopDaemon({obj_id})`.
 
-`describe` ⊕
+`describe` |ADD|
   For an object: called before the object's description is output.  For a
   room: called before the room's (long) description is output.
 
   For an object: called before the object's description is output.  For a
   room: called before the room's (long) description is output.
 
@@ -471,7 +477,7 @@ Object's value being considered first.
 `e_to`
   See `d_to`.
 
 `e_to`
   See `d_to`.
 
-`each_turn` ⊕
+`each_turn` |ADD|
   Invoked at the end of each turn (after all appropriate daemons and
   timers) whenever the object is in scope.  The `{value}` can be a string,
   or a routine.
   Invoked at the end of each turn (after all appropriate daemons and
   timers) whenever the object is in scope.  The `{value}` can be a string,
   or a routine.
@@ -518,7 +524,7 @@ Object's value being considered first.
   `inventory_stage` has the value 2, and the routine should return `false`
   to continue, or `true` to stop processing and produce no further output.
 
   `inventory_stage` has the value 2, and the routine should return `false`
   to continue, or `true` to stop processing and produce no further output.
 
-`life` ⊕
+`life` |ADD|
   For an `animate` object: receives person-to-person actions (`Answer`,
   `Ask`, `Attack`, `Give`, `Kiss`, `Order`, `Show`, `Tell`, `ThrowAt` and
   `WakeOther`) for which this is the `{noun}`.  The `{value}` is a routine
   For an `animate` object: receives person-to-person actions (`Answer`,
   `Ask`, `Attack`, `Give`, `Kiss`, `Order`, `Show`, `Tell`, `ThrowAt` and
   `WakeOther`) for which this is the `{noun}`.  The `{value}` is a routine
@@ -545,7 +551,7 @@ Object's value being considered first.
 `n_to`
   See `d_to`.
 
 `n_to`
   See `d_to`.
 
-`name` ⊕
+`name` |ADD|
   Defines a space-separated list of words which are added to the Inform
   dictionary.  Each word can be supplied in apostrophes '...'  or quotes
   "..."; in all other cases only words in apostrophes update the
   Defines a space-separated list of words which are added to the Inform
   dictionary.  Each word can be supplied in apostrophes '...'  or quotes
   "..."; in all other cases only words in apostrophes update the
@@ -566,7 +572,7 @@ Object's value being considered first.
 `nw_to`
   See `d_to`.
 
 `nw_to`
   See `d_to`.
 
-`orders` ⊕
+`orders` |ADD|
   For an `animate` or `talkable` object: the `{value}` is a routine called
   to carry out the player's orders.  The routine should return `false` to
   continue, or `true` to stop processing the action and produce no further
   For an `animate` or `talkable` object: the `{value}` is a routine called
   to carry out the player's orders.  The routine should return `false` to
   continue, or `true` to stop processing the action and produce no further
@@ -649,6 +655,8 @@ Object's value being considered first.
   For a `lockable` object: the `{obj_id}` (generally some kind of key)
   needed to lock and unlock the object, or `nothing` if no key fits.
 
   For a `lockable` object: the `{obj_id}` (generally some kind of key)
   needed to lock and unlock the object, or `nothing` if no key fits.
 
+.. _object-attrs:
+
 Object attributes
 =================
 
 Object attributes
 =================
 
@@ -749,6 +757,8 @@ Object attributes
 `worn`
      For a `clothing` object: is being worn.
 
 `worn`
      For a `clothing` object: is being worn.
 
+.. _entry-points:
+
 Optional entry points
 =====================
 
 Optional entry points
 =====================
 
@@ -823,6 +833,8 @@ These routines, if you supply them, are called when shown.
 `UnknownVerb()`
   Called when an unusual verb is encountered.
 
 `UnknownVerb()`
   Called when an unusual verb is encountered.
 
+.. _group-1-actions:
+
 Group 1 actions
 ===============
 
 Group 1 actions
 ===============
 
@@ -878,11 +890,15 @@ and the debug tools.
 `XTree`           "`TREE`"
 ===============   ===================================================
 
 `XTree`           "`TREE`"
 ===============   ===================================================
 
+.. _group-2-actions:
+
 Group 2 actions
 ===============
 
 Group 2 actions usually work, given the right circumstances.
 
 Group 2 actions
 ===============
 
 Group 2 actions usually work, given the right circumstances.
 
+.. tabularcolumns:: |l|p{5in}|
+
 =============   =============================================================
 `Close`         "`CLOSE [UP]`", "`COVER [UP]`", "`SHUT [UP]`"
 `Disrobe`       "`DISROBE`", "`DOFF`", "`REMOVE`", "`SHED`", "`TAKE OFF`"
 =============   =============================================================
 `Close`         "`CLOSE [UP]`", "`COVER [UP]`", "`SHUT [UP]`"
 `Disrobe`       "`DISROBE`", "`DOFF`", "`REMOVE`", "`SHED`", "`TAKE OFF`"
@@ -940,12 +956,16 @@ Group 2 actions usually work, given the right circumstances.
 `Wear`          "`DON`", "`PUT ON`", "`WEAR`"
 =============   =============================================================
 
 `Wear`          "`DON`", "`PUT ON`", "`WEAR`"
 =============   =============================================================
 
+.. _group-3-actions:
+
 Group 3 actions
 ===============
 
 Group 3 actions are by default stubs which output a message and stop at the
 "before" stage (so there is no "after" stage).
 
 Group 3 actions
 ===============
 
 Group 3 actions are by default stubs which output a message and stop at the
 "before" stage (so there is no "after" stage).
 
+.. tabularcolumns:: |l|p{5in}|
+
 =============   =============================================================
 `Answer`        "`ANSWER TO`", "`SAY TO`",
                 "`SHOUT TO`", "`SPEAK TO`"
 =============   =============================================================
 `Answer`        "`ANSWER TO`", "`SAY TO`",
                 "`SHOUT TO`", "`SPEAK TO`"
@@ -1016,6 +1036,8 @@ Fake actions
 Fake actions handle some special cases, or represent "real" actions from
 the viewpoint of the second object.
 
 Fake actions handle some special cases, or represent "real" actions from
 the viewpoint of the second object.
 
+.. tabularcolumns:: |l|p{5in}|
+
 ================   ========================================================
 `LetGo`            Generated by `Remove`.
 `ListMiscellany`   Outputs a range of inventory messages.
 ================   ========================================================
 `LetGo`            Generated by `Remove`.
 `ListMiscellany`   Outputs a range of inventory messages.
Inform Beginner's Guide