Address more of the TODO items.

[ibg.git] / chapters / 16.rst

diff --git a/chapters/16.rst b/chapters/16.rst
index 6d358e0b5a49aaaf1ee4a0fabe8b35579140b557..c2543c44b83d8cf1778790e06d5d5c56d8953f3e 100644 (file)
--- a/chapters/16.rst
+++ b/chapters/16.rst
@@ -1,22 +1,18 @@
-===================
-Debugging your game
-===================
+=====================
+ Debugging your game
+=====================

 
 .. only:: html
 
   .. image:: /images/picN.png
      :align: left
 
 
 .. only:: html
 
   .. image:: /images/picN.png
      :align: left
 

-.. raw:: latex
-
-   \dropcap{n}
-
-obody understands the phrase *errare humanum est* quite in the same way 
-as a programmer does. Computers are highly efficient machines capable of 
-wondrous calculations, but they lack imagination and insist that every 
-single item thrown at them must be presented according to certain rules 
-previously defined. You can't negotiate with a computer; you either bow 
-in submission or bite the dust.
+|N|\obody understands the phrase *errare humanum est* quite in the same
+way as a programmer does. Computers are highly efficient machines 
+capable of wondrous calculations, but they lack imagination and insist 
+that every single item thrown at them must be presented according to 
+certain rules previously defined. You can't negotiate with a computer; 
+you either bow in submission or bite the dust.

 
 Inform behaves no differently. If you make a typing or syntax mistake, 
 the compiler will send you back to revise your work. "It was just a 
 
 Inform behaves no differently. If you make a typing or syntax mistake, 
 the compiler will send you back to revise your work. "It was just a 


@@ -58,11 +54,10 @@ always pays off in the end.)
 
 To help you out in this daunting task, Inform has a stock of special
 actions: the debugging verbs. They become available at run-time when the
 
 To help you out in this daunting task, Inform has a stock of special
 actions: the debugging verbs. They become available at run-time when the

-source file is compiled in :term:`Debug mode` (``-D switch``). When you are
-ready to release your game, you’ll have to recompile, switching off Debug
-to avoid allowing the players to benefit from the debugging verbs.  We'll
-cover briefly a few of these actions, and tell you what they do.
-
+source file is compiled in :term:`Debug mode` (:option:`-D` switch). When
+you are ready to release your game, you’ll have to recompile, switching off
+Debug to avoid allowing the players to benefit from the debugging verbs.
+We'll cover briefly a few of these actions, and tell you what they do.

 
 Command lists
 =============
 
 Command lists
 =============


@@ -269,11 +264,16 @@ GOTO *number*
 
 PURLOIN *object*
 
 
 PURLOIN *object*
 

+  .. Generated by autoindex
+  .. index::
+     pair: scenery; library attribute
+     pair: static; library attribute
+

   PURLOIN works exactly as TAKE , with the nice addition that it doesn't 
   matter where the object is: in another room, inside a locked 
   container, in the claws of the bloodthirsty dragon. More dangerously, 
   it doesn't matter if the object is takeable, so you may purloin 
   PURLOIN works exactly as TAKE , with the nice addition that it doesn't 
   matter where the object is: in another room, inside a locked 
   container, in the claws of the bloodthirsty dragon. More dangerously, 
   it doesn't matter if the object is takeable, so you may purloin 

-  ``static`` or ``scenery`` objects. PURLOIN is useful in a variety of 
+  :attr:`static` or :attr:`scenery` objects. PURLOIN is useful in a variety of 

   situations, basically when you want to test a particular feature of 
   the game that requires the player character to have some objects 
   handy. Instead of tediously collecting them, you may simply PURLOIN 
   situations, basically when you want to test a particular feature of 
   the game that requires the player character to have some objects 
   handy. Instead of tediously collecting them, you may simply PURLOIN 


@@ -282,22 +282,28 @@ PURLOIN *object*
 
 ABSTRACT *object* TO *object*
 
 
 ABSTRACT *object* TO *object*
 

+  .. Generated by autoindex
+  .. index::
+     pair: animate; library attribute
+     pair: container; library attribute
+     pair: supporter; library attribute
+

   This verb enables you to move the first *object* to the second 
   *object*. As with PURLOIN , both objects can be anywhere in the game. 
   Bear in mind that the second object should logically be a 
   This verb enables you to move the first *object* to the second 
   *object*. As with PURLOIN , both objects can be anywhere in the game. 
   Bear in mind that the second object should logically be a 

-  ``container``, a ``supporter`` , or something ``animate``.
+  :attr:`container`, a :attr:`supporter` , or something :attr:`animate`.

 
 
 
 

-Infix: the harlot's perogative
-==============================
+Infix: the harlot's prerogative
+===============================

 
 

-The basic debugging verbs are fairly versatile, easy to use, and don't 
-consume a lot of memory. Occasionally though, you'll meet a bug which 
-you simply can't catch using regular techniques, and that’s when you 
-might want to investigate the Infix debugger. You'll need to compile 
-using the ``-X`` switch, and you'll then be able to monitor and modify 
-almost all of your game’s data and objects. For instance, you can use 
-";" to inspect -- and change -- a variable:
+The basic debugging verbs are fairly versatile, easy to use, and don't
+consume a lot of memory. Occasionally though, you'll meet a bug which you
+simply can't catch using regular techniques, and that’s when you might want
+to investigate the Infix debugger. You'll need to compile using the
+:option:`-X` switch, and you'll then be able to monitor and modify almost
+all of your game’s data and objects. For instance, you can use ";" to
+inspect -- and change -- a variable:

 
 .. code-block:: transcript
 
 
 .. code-block:: transcript
 


@@ -318,8 +324,8 @@ almost all of your game’s data and objects. For instance, you can use
   In that game you scored 0 out of a possible 2, in 2 turns.
 
 It's often quite maddening to realise that some variable is still 
   In that game you scored 0 out of a possible 2, in 2 turns.
 
 It's often quite maddening to realise that some variable is still 

-``false`` because the Chalk puzzle didn't work properly, and that you 
-can't test the Cheese puzzle until the variable becomes ``true``. Rather 
+:const:`false` because the Chalk puzzle didn't work properly, and that you 
+can't test the Cheese puzzle until the variable becomes :const:`true`. Rather 

 than quit, fix the Chalk, recompile, play back to the current position 
 and only *then* tackle the Cheese, how much easier to just change the 
 variable in mid-stream, and carry right on.
 than quit, fix the Chalk, recompile, play back to the current position 
 and only *then* tackle the Cheese, how much easier to just change the 
 variable in mid-stream, and carry right on.


@@ -372,8 +378,6 @@ change:
   "OK, Herr Tell, now you're in real trouble.
   ...
 
   "OK, Herr Tell, now you're in real trouble.
   ...
 

-.. todo:: "Herr" above is italicized.  Was that a mistake in the original text?
-

 Infix is quite complex -- there are more commands than those we have 
 shown you -- so while it's good to have available, it's not really a 
 tool for novices. If you do use it, be careful: you get a lot of runtime 
 Infix is quite complex -- there are more commands than those we have 
 shown you -- so while it's good to have available, it's not really a 
 tool for novices. If you do use it, be careful: you get a lot of runtime 


@@ -384,7 +388,6 @@ to make permanent amendments, you still need to edit the source file.
 You won't need it often, but Infix can sometimes provide quick answers 
 to tricky problems.
 
 You won't need it often, but Infix can sometimes provide quick answers 
 to tricky problems.
 

-

 No matter what
 ==============
 
 No matter what
 ==============
 


@@ -420,10 +423,14 @@ then wrote:
   * Benny will force the player back into the cafe even when the key is
     dropped in the café, or put on the counter (in Benny's plain sight!).
 
   * Benny will force the player back into the cafe even when the key is
     dropped in the café, or put on the counter (in Benny's plain sight!).
 

-Of course, the code we've offered you in this edition takes care of 
+Of course, the code we've offered you in *this* edition takes care of 

 those embarrassing issues, but it might very well happen that a few more 
 undetected absurdities pop up from now on.
 
 those embarrassing issues, but it might very well happen that a few more 
 undetected absurdities pop up from now on.
 

+.. Generated by autoindex
+.. index::
+   single: RAIF
+

 The final stage of debugging must happen elsewhere, at the hands of some 
 wilful, headstrong and determined beta-testers; these are the people 
 who, if you’re lucky, will methodically tear your game to shreds and 
 The final stage of debugging must happen elsewhere, at the hands of some 
 wilful, headstrong and determined beta-testers; these are the people 
 who, if you’re lucky, will methodically tear your game to shreds and 


@@ -437,32 +444,29 @@ The IF community offers some beta-testing resources, or you can always
 ask in RAIF for kind souls willing to have a go at your game. Remember 
 the golden rules:
 
 ask in RAIF for kind souls willing to have a go at your game. Remember 
 the golden rules:
 

-  * **Expect no mercy**. Although it hurts, a merciless approach is what 
-    you need at this time; much better to discover your errors and 
-    oversights now, before you release the game more widely. And don't 
-    forget to acknowledge your testers' assistance somewhere within the 
-    game.
-
-  * **Never say never**.  If your testers suggest that the game should 
-    respond better to an attempted action, don't automatically respond 
-    with "No one's going to try that!" They already have, and will again 
-    -- be grateful for your testers' devious minds and twisted psyches. 
-    Although a normal player won't try all of those oddball things, 
-    every player is bound to try at least one, and their enjoyment will 
-    be greater, the reality enhanced, if the game "understands".
-
-  * **Ask for more**. Don't treat your testers simply as validators of 
-    your programming skills, but rather as reviewers of your 
-    storytelling abilities. Encourage them to comment on how well the 
-    pieces fit together, and to make suggestions -- small or radical -- 
-    for improvement; don't necessarily reject good ideas just because 
-    implementing them "will take too long". For example: "the scene in 
-    the Tower of London doesn't somehow seem to belong in an Arabian 
-    Nights game", or "having to solve three puzzles in a row just to 
-    discover the plate of sheep's eyes is a little over the top", or 
-    "this five-room trek across the desert really is a bit dull; 
-    perhaps you could add a quicksand or something to liven it up?", or 
-    "the character of the eunuch in the harem seems to be lacking in 
-    something". That is, view the testers collectively not as simple 
-    spell-checkers, but rather as collaborative editors on your latest 
-    novel.
+* **Expect no mercy**. Although it hurts, a merciless approach is what you
+  need at this time; much better to discover your errors and oversights
+  now, before you release the game more widely. And don't forget to
+  acknowledge your testers' assistance somewhere within the game.
+
+* **Never say never**.  If your testers suggest that the game should
+  respond better to an attempted action, don't automatically respond with
+  "No one's going to try that!" They already have, and will again -- be
+  grateful for your testers' devious minds and twisted psyches.  Although a
+  normal player won't try *all* of those oddball things, every player is
+  bound to try at least *one*, and their enjoyment will be greater, the
+  reality enhanced, if the game "understands".
+
+* **Ask for more**. Don't treat your testers simply as validators of your
+  programming skills, but rather as reviewers of your storytelling
+  abilities. Encourage them to comment on how well the pieces fit together,
+  and to make suggestions -- small or radical -- for improvement; don't
+  necessarily reject good ideas just because implementing them "will take
+  too long". For example: "the scene in the Tower of London doesn't somehow
+  seem to belong in an Arabian Nights game", or "having to solve three
+  puzzles in a row just to discover the plate of sheep's eyes is a little
+  over the top", or "this five-room trek across the desert really is a bit
+  dull; perhaps you could add a quicksand or something to liven it up?", or
+  "the character of the eunuch in the harem seems to be lacking in
+  something". That is, view the testers collectively not as simple
+  spell-checkers, but rather as collaborative editors on your latest novel.