Add special RST roles for the Inform entities.

[ibg.git] / chapters / 16.rst

diff --git a/chapters/16.rst b/chapters/16.rst
index dbbd704b9318f14ba79a10f063d17fc4c7799449..702a59437b02e07efd5b6adc65ee8eb5903cfc77 100644 (file)
--- a/chapters/16.rst
+++ b/chapters/16.rst
@@ -1,6 +1,6 @@
-===================
-Debugging your game
-===================
+=====================
+ Debugging your game
+=====================

 
 .. only:: html
 
 
 .. only:: html
 


@@ -56,14 +56,13 @@ you must make the appropriate changes. (There is also the case when you
 can't find the mistake. Don't worry, it's there somewhere. Persistence 
 always pays off in the end.)
 
 can't find the mistake. Don't worry, it's there somewhere. Persistence 
 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 
-source file is compiled in **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. 
+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` (: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.
 
 We'll cover briefly a few of these actions, and tell you what they do.
 

-

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


@@ -237,20 +236,18 @@ TIMERS (or TIMERS ON ) and TIMERS OFF
 
 TRACE (or TRACE ON ), TRACE *number* and TRACE OFF
 
 
 TRACE (or TRACE ON ), TRACE *number* and TRACE OFF
 

-  If you turn on this powerful verb, you'll be able to follow the 
-  activity of the **parser** -- that part of the library which tries to 
-  make sense of what the player types -- and this will indeed be a 
-  wonderful moment of gratitude that someone else took the trouble of 
-  writing it. Since the parser does so many things, you can decide the 
-  level of detail about the displayed information with the *number* 
-  parameter, which can go from 1 (minimum info) to 5 (maximum info). By 
-  default, TRACE ON and TRACE with no number sets level 1. Trace level 
-  1 shows the grammar line that the parser is thinking about, while 
-  level 2 shows each individual token on each grammar line that it 
-  tries. The information displayed with higher levels may become quite 
-  hacky, and you are advised to use this feature only if nothing else 
-  helps.
-
+  If you turn on this powerful verb, you'll be able to follow the activity
+  of the :term:`parser` -- that part of the library which tries to make
+  sense of what the player types -- and this will indeed be a wonderful
+  moment of gratitude that someone else took the trouble of writing
+  it. Since the parser does so many things, you can decide the level of
+  detail about the displayed information with the *number* parameter, which
+  can go from 1 (minimum info) to 5 (maximum info). By default, TRACE ON
+  and TRACE with no number sets level 1. Trace level 1 shows the grammar
+  line that the parser is thinking about, while level 2 shows each
+  individual token on each grammar line that it tries. The information
+  displayed with higher levels may become quite hacky, and you are advised
+  to use this feature only if nothing else helps.

 
 Super-powers
 ============
 
 Super-powers
 ============


@@ -275,7 +272,7 @@ PURLOIN *object*
   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 
   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 


@@ -287,19 +284,19 @@ ABSTRACT *object* TO *object*
   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
 


@@ -320,8 +317,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.


@@ -374,7 +371,12 @@ 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?
+.. todo::
+
+   "Herr" above is italicized.  Was that a mistake in the original text?
+
+   Update: I don't think so.  In 08.rst, lines 465 and 516, "Herr" is
+   explicitly underlined (which probably appears italicized on output).

 
 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 
 
 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 


@@ -386,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
 ==============
 


@@ -422,7 +423,7 @@ 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.
 


@@ -439,32 +440,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.