From: Glenn Hutchings Date: Wed, 26 Oct 2016 09:22:21 +0000 (+0100) Subject: Address more of the TODO items. X-Git-Url: https://jxself.org/git/?a=commitdiff_plain;h=8009937904cf79341a9c23c9c5e7b541606bfcb6;p=ibg.git Address more of the TODO items. --- diff --git a/about.rst b/about.rst index 160190e..0a95ff3 100644 --- a/about.rst +++ b/about.rst @@ -112,7 +112,11 @@ Inform statement: as meaning "display on the player's screen the arbitrary character or characters which are represented here by the placeholder *string*". -Examples might include:: +Examples might include: + +.. include:: /config/typethis.rst + +:: print "Hello world!"; print "Fourscore and seven years ago our fathers brought forth on @@ -120,14 +124,7 @@ Examples might include:: the people, by the people, for the people shall not perish from the earth."; -We place the "TYPE" symbol alongside game fragments which you can type in -as a part of our working examples. This differentiates them from other -code snippets whose only purpose is to illustrate some particular feature. - -.. todo:: - - The "TYPE" symbol doesn't really work here. Think of a better way to - indicate typed-in fragments. +.. include:: /config/typeinfo.rst Useful Internet resources ========================= diff --git a/chapters/03.rst b/chapters/03.rst index a50db44..06fcffb 100644 --- a/chapters/03.rst +++ b/chapters/03.rst @@ -47,6 +47,8 @@ that we design will start out like this. Follow these steps: #. In that folder, use your text editor to create this source file ``Heidi.inf``: + .. include:: /config/typethis.rst + .. code-block:: inform !% -SD @@ -92,20 +94,23 @@ that we design will start out like this. Follow these steps: learn Inform more quickly by trying it for yourself, rather than just taking our word for how things work. - .. todo:: +#. In the same folder, use your text editor to create the compilation + support file ``Heidi.bat`` (on a PC): - Again, revisit the TYPE symbol. Maybe a standard indicator above - each snippet? + .. include:: /config/typethis.rst -#. In the same folder, use your text editor to create the compilation - support file ``Heidi.bat`` (on a PC):: + :: ..\..\Lib\Base\Inform Heidi +include_path=.\,..\..\Lib\Base,..\..\Lib\Contrib | more pause "at end of compilation" - or ``Heidi.command`` (on a Macintosh):: + or ``Heidi.command`` (on a Macintosh): + + .. include:: /config/typethis.rst + + :: cd ~/Inform/Games/Heidi/ @@ -495,6 +500,8 @@ At this stage, you should study the four room definitions, comparing them with the sketch map until you're comfortable that you understand how to create simple rooms and define the connections between them. +.. include:: /config/typethis.rst + .. code-block:: inform !============================================================================ @@ -596,6 +603,8 @@ relevant vocabulary so that the player can use whatever term seems appropriate to her, with a good chance of it being understood. We add a line to each definition: +.. include:: /config/typethis.rst + .. code-block:: inform Object bird "baby bird" @@ -752,6 +761,8 @@ Adding the tree and the branch The description of the clearing mentions a tall sycamore tree, up which the player character supposedly "climbs". We'd better define it: +.. include:: /config/typethis.rst + .. code-block:: inform Object tree "tall sycamore tree" clearing @@ -769,6 +780,8 @@ labelling the tree as :attr:`scenery` we suppress that, and also prevent it from being picked up by the player character. One final object: the branch at the top of the tree. Again, not many surprises in this definition: +.. include:: /config/typethis.rst + .. code-block:: inform Object branch "wide firm bough" top_of_tree @@ -853,6 +866,8 @@ carrying the bird and the nest separately: we want the player character to put the bird into the nest first. One easy way to enforce this is by adding a line near the top of the file: +.. include:: /config/typethis.rst + .. code-block:: inform !============================================================================ @@ -875,6 +890,8 @@ to put the bird in the nest, take the nest to the top of the tree, and place it on the branch; when that happens, the game should be over. This is one way of making it happen: +.. include:: /config/typethis.rst + .. code-block:: inform Object branch "wide firm bough" top_of_tree diff --git a/chapters/04.rst b/chapters/04.rst index 46e1858..b01d773 100644 --- a/chapters/04.rst +++ b/chapters/04.rst @@ -4,6 +4,8 @@ .. highlight:: inform +.. default-role:: samp + .. epigraph:: | |CENTER| *G was a gamester, who had but ill-luck;* @@ -93,20 +95,16 @@ room is an object, each item that the player sees and touches is an object; indeed the player herself is also an object (one that's automatically defined by the library). -.. todo:: - - The set-off below needs to be tweaked or perhaps a custom lexer - created to get italics in the right places. - -The general model of an :term:`object` definition looks like this:: +The general model of an :term:`object` definition looks like this: - Object obj_id "external_name" parent_obj_id - with property value , - property value , - ... - property value , - has attribute attribute ... attribute - ; + | `Object {obj_id} "{external_name}" {parent_obj_id}` + | `with` + | `{property} {value},` + | `{property} {value},` + | `...` + | `{property} {value},` + | `has {attribute} {attribute} ... {attribute}` + | `;` The definition starts with the word ``Object`` and ends with a semicolon; in between are three major blocks of information: @@ -120,22 +118,22 @@ Object headers An object header comprises up to three items, all optional: -* An internal ``obj_id`` by which other objects refer to this object. It's +* An internal `{obj_id}` by which other objects refer to this object. It's a single word (though it can contain digits and underscores) of up to thirty-two characters, and it must be unique within the game. You can - omit the ``obj_id`` if this object isn't referred to by any other + omit the `{obj_id}` if this object isn't referred to by any other objects. For example: ``bird``, ``tree``, ``top_of_tree``. -* An ``external_name``, in double quotes, which is what the interpreter +* An `{external_name}`, in double quotes, which is what the interpreter uses when referring to the object. It can be one or more words, and need not be unique (for instance, you might have several ``"Somewhere in the desert"`` rooms). Although not mandatory, it's best to give *every* - object an ``external_name``. For example: ``"baby bird"``, ``"tall + object an `{external_name}`. For example: ``"baby bird"``, ``"tall sycamore tree"``, ``"At the top of the tree"``. -* The internal ``obj_id`` of another object which is the initial location +* The internal `{obj_id}` of another object which is the initial location of this object (its "parent" -- see the next section) at the start of the game. This is omitted from objects which have no initial parent; it's *always* omitted from a room. diff --git a/chapters/05.rst b/chapters/05.rst index 8e3fb54..7c2ecba 100644 --- a/chapters/05.rst +++ b/chapters/05.rst @@ -60,6 +60,8 @@ LISTEN TO NEST or LISTEN TO TREE, but fairly inappropriate here; we really need to substitute a more relevant response after LISTEN TO BIRD. Here's how we do it: +.. include:: /config/typethis.rst + .. code-block:: inform Object bird "baby bird" forest @@ -185,6 +187,8 @@ which might lead her to believe that she can go inside: Again, that isn't perhaps the most appropriate response, but it's easy to change: +.. include:: /config/typethis.rst + .. code-block:: inform Object before_cottage "In front of a cottage" @@ -249,6 +253,8 @@ response: The situation here is similar to our LISTEN TO BIRD problem, and the solution we adopt is similar as well: +.. include:: /config/typethis.rst + .. code-block:: inform Object cottage "tiny cottage" before_cottage @@ -288,6 +294,8 @@ currently gives the completely misleading response "I don't think much is to be achieved by that"). Yet another opportunity to use a :prop:`before` property, but now with a difference. +.. include:: /config/typethis.rst + .. code-block:: inform Object tree "tall sycamore tree" clearing @@ -360,6 +368,8 @@ interception not on an object-by-object basis, as we have been doing so far, but instead for every :act:`Drop` which takes place in our troublesome ``top_of_tree`` room. This is what we have to write: +.. include:: /config/typethis.rst + .. code-block:: inform Object top_of_tree "At the top of the tree" @@ -473,6 +483,8 @@ nest, or vice versa. It would be better not to end the game until we'd checked for the bird actually being in the nest; fortunately, that's easy to do: +.. include:: /config/typethis.rst + .. code-block:: inform Object branch "wide firm bough" top_of_tree diff --git a/chapters/06.rst b/chapters/06.rst index c0cd6da..e242057 100644 --- a/chapters/06.rst +++ b/chapters/06.rst @@ -26,7 +26,11 @@ Initial setup ============= Our starting point is much the same as last time. Here's a basic -``Tell.inf``:: +``Tell.inf``: + +.. include:: /config/typethis.rst + +:: !% -SD !=========================================================================== @@ -317,7 +321,11 @@ In fact, for any object both the block of properties and the block of attributes are optional and can be omitted if there's nothing to be specified. Now that the :attr:`light` attribute is being provided automatically and there aren't any other attributes to set, the word -``has`` can be left out. Here's the class again:: +``has`` can be left out. Here's the class again: + +.. include:: /config/typethis.rst + +:: Class Room has light; @@ -348,7 +356,11 @@ We use the ``Room`` class in "William Tell", and a few other classes besides. Here's a ``Prop`` class (that's "Prop" in the sense of a theatrical property rather than a supportive device), useful for scenic items whose only role is to sit waiting in the background on the off-chance -that the player might think to EXAMINE them:: +that the player might think to EXAMINE them: + +.. include:: /config/typethis.rst + +:: Class Prop with before [; @@ -461,7 +473,11 @@ an object with the :attr:`static` attribute, an attempt to TAKE it results in "That's fixed in place" -- acceptable in the case of Heidi's branch object (which is indeed supposed to be part of the tree), less so for items which are simply large and heavy. This ``Furniture`` class might sometimes -be more appropriate:: +be more appropriate: + +.. include:: /config/typethis.rst + +:: Class Furniture with before [; diff --git a/chapters/07.rst b/chapters/07.rst index c4beedc..fad0f1c 100644 --- a/chapters/07.rst +++ b/chapters/07.rst @@ -22,7 +22,11 @@ stallholder. Defining the street =================== -This is the street room, the location where the game starts:: +This is the street room, the location where the game starts: + +.. include:: /config/typethis.rst + +:: Room street "A street in Altdorf" with description [; @@ -153,7 +157,11 @@ Adding some props The street's description mentions various items -- the gate, the people, etc. -- which ought to exist within the game (albeit only in minimal form) to sustain the illusion of hustle and bustle. Our ``Prop`` class is ideal -for this:: +for this: + +.. include:: /config/typethis.rst + +:: Prop "south gate" street with name 'south' 'southern' 'wooden' 'gate', @@ -280,7 +288,11 @@ The player's possessions ======================== Since our ``Initialise`` routine has already mentioned them, we might as -well define Wilhelm's bow and arrows:: +well define Wilhelm's bow and arrows: + +.. include:: /config/typethis.rst + +:: Object bow "bow" with name 'bow', @@ -310,7 +322,11 @@ that our ``Initialise`` routine goes on to add a :attr:`worn` attribute to the quiver. An empty quiver is pretty useless, so here's the class used to define -Wilhelm's stock of arrows. This class has some unusual features:: +Wilhelm's stock of arrows. This class has some unusual features: + +.. include:: /config/typethis.rst + +:: Class Arrow with name 'arrow' 'arrows//p', @@ -355,7 +371,11 @@ listing them individually in this clumsy fashion: The interpreter will do this for us if our objects are "indistinguishable", best achieved by making them members of a class which includes both :prop:`name` and :prop:`plural` properties. We define the actual arrows -very simply, like this:: +very simply, like this: + +.. include:: /config/typethis.rst + +:: Arrow "arrow" quiver; Arrow "arrow" quiver; @@ -400,7 +420,11 @@ of cakes". Moving further along the street =============================== -As Wilhelm moves north towards the square, he comes to this room:: +As Wilhelm moves north towards the square, he comes to this room: + +.. include:: /config/typethis.rst + +:: Room below_square "Further along the street" with description @@ -410,7 +434,11 @@ As Wilhelm moves north towards the square, he comes to this room:: n_to south_square, s_to street; -No surprises there, nor in most of the supporting scenery objects. :: +No surprises there, nor in most of the supporting scenery objects. + +.. include:: /config/typethis.rst + +:: Furniture stall "fruit and vegetable stall" below_square with name 'fruit' 'veg' 'vegetable' 'stall' 'table', @@ -506,7 +534,11 @@ can be a real nightmare. But not here: we've kept our three NPCs -- Helga, Walter and the vogt -- as simple as possible. Nevertheless, we can establish some fundamental -principles; here's the class upon which we base our NPCs:: +principles; here's the class upon which we base our NPCs: + +.. include:: /config/typethis.rst + +:: Class NPC with life [; @@ -543,7 +575,11 @@ such as ASK HELGA ABOUT APPLE and TELL WALTER ABOUT BABIES, telling players that in this game we've implemented only a simpler TALK verb (which we describe in :ref:`verbs`). -Based on the NPC class we've created, here's Helga:: +Based on the NPC class we've created, here's Helga: + +.. include:: /config/typethis.rst + +:: NPC stallholder "Helga" below_square with name 'stallholder' 'greengrocer' 'monger' 'shopkeeper' 'merchant' diff --git a/chapters/08.rst b/chapters/08.rst index db5715c..45c54d2 100644 --- a/chapters/08.rst +++ b/chapters/08.rst @@ -25,7 +25,11 @@ The south side of the square ============================ The town square, notionally one enormous open space, is represented by -three rooms. Here's the south side:: +three rooms. Here's the south side: + +.. include:: /config/typethis.rst + +:: Room south_square "South side of the square" with description @@ -131,7 +135,11 @@ room:: n_to north_square, s_to south_square; -and the pole:: +and the pole: + +.. include:: /config/typethis.rst + +:: Furniture pole "hat on a pole" mid_square with name 'wooden' 'pole' 'pine' 'hat' 'black' 'red' 'brim' 'feathers', @@ -516,7 +524,11 @@ we didn't give it to him earlier in the game), relocate to the final room using ``PlayerTo(marketplace)``, and finally ``return true`` to tell the interpreter that we've handled this part of the :act:`Go` action ourselves. And so, at long last, here's the complete code for the ``mid_square``, the -most complicated object in the whole game:: +most complicated object in the whole game: + +.. include:: /config/typethis.rst + +:: Room mid_square "Middle of the square" with description @@ -572,7 +584,11 @@ The north side of the square ============================ The only way to get here is by saluting the pole and then moving north; not -very likely, but good game design is about predicting the unpredictable. :: +very likely, but good game design is about predicting the unpredictable. + +.. include:: /config/typethis.rst + +:: Room north_square "North side of the square" with description @@ -606,7 +622,11 @@ the end of every turn; these are the values that it's expecting to find: In this game, we never set :var:`deadflag` to 1, but we do use values of 2 and 3. So we'd better define a ``DeathMessage`` routine to tell players -what they've done:: +what they've done: + +.. include:: /config/typethis.rst + +:: [ DeathMessage; print "You have screwed up a favourite folk story"; ]; diff --git a/chapters/09.rst b/chapters/09.rst index ac5ccc8..d03ea32 100644 --- a/chapters/09.rst +++ b/chapters/09.rst @@ -23,7 +23,11 @@ The marketplace =============== The ``marketplace`` room is unremarkable, and the ``tree`` growing there -has only one feature of interest:: +has only one feature of interest: + +.. include:: /config/typethis.rst + +:: Room marketplace "Marketplace near the square" with description @@ -270,7 +274,11 @@ want to check on the characteristics of an object, possibly then displaying a message. We don't know exactly *which* object is to be checked, so we need to write our routine in a generalised way, capable of checking any object which we choose; that is, we'll supply the object to be checked as -an argument. Here's the routine:: +an argument. Here's the routine: + +.. include:: /config/typethis.rst + +:: [ BowOrArrow o; if (o == bow or nothing || o ofclass Arrow) return true; @@ -346,7 +354,12 @@ to 3 -- the "You have screwed up" ending, display a message, and be done. Gessler the governor ==================== -There's nothing in Gessler's definition that we haven't already encountered:: +There's nothing in Gessler's definition that we haven't already +encountered: + +.. include:: /config/typethis.rst + +:: NPC governor "governor" marketplace with name 'governor' 'vogt' 'Hermann' 'Gessler', @@ -393,7 +406,11 @@ Walter and the apple ==================== Since he's been with you throughout, it's really about time we defined -Walter:: +Walter: + +.. include:: /config/typethis.rst + +:: NPC son "your son" with name 'son' 'your' 'boy' 'lad' 'Walter', @@ -503,7 +520,11 @@ It's saying: The apple's moment of glory has arrived! Its :prop:`before` property responds to the :act:`FireAt` action by setting :var:`deadflag` to 2. When -that happens, the game is over; the player has won. :: +that happens, the game is over; the player has won. + +.. include:: /config/typethis.rst + +:: Object apple "apple" with name 'apple', @@ -571,13 +592,21 @@ might be tempted to try to UNTIE WALTER; unlikely, but as we've said before, anticipating the improbable is part of the craft of IF. For this, and for all new actions, two things are required. We need a grammar definition, spelling out the structure of the English sentences which we're -prepared to accept:: +prepared to accept: + +.. include:: /config/typethis.rst + +:: Verb 'untie' 'unfasten' 'unfix' 'free' 'release' * noun -> Untie; and we need a routine to handle the action in the default situation (where -the action isn't intercepted by an object's :prop:`before` property). :: +the action isn't intercepted by an object's :prop:`before` property). + +.. include:: /config/typethis.rst + +:: [ UntieSub; print_ret "You really shouldn't try that."; ]; @@ -667,7 +696,11 @@ this game, so we always generate a refusal of some sort. pair: Salute; library action The next action is :act:`Salute`, provided in case Wilhelm chooses to defer -to the hat on the pole. Here's the default action handler:: +to the hat on the pole. Here's the default action handler: + +.. include:: /config/typethis.rst + +:: [ SaluteSub; if (noun has animate) print_ret (The) noun, " acknowledges you."; @@ -678,7 +711,11 @@ You'll notice that this is slightly more intelligent than our :act:`Untie` handler, since it produces different responses depending on whether the object being saluted -- stored in the :var:`noun` variable -- is :attr:`animate` or not. But it's basically doing the same job. And here's -the grammar:: +the grammar: + +.. include:: /config/typethis.rst + +:: Verb 'bow' 'nod' 'kowtow' 'genuflect' * 'at'/'to'/'towards' noun -> Salute; @@ -733,7 +770,11 @@ library, and Inform's rule is that a verb can appear in only one ``Verb`` definition. The wrong solution: edit ``Grammar.h`` to *physically* add lines to the existing definitions (it's almost never a good idea to make changes to the standard library files). The right solution: use ``Extend`` -to *logically* add those lines. If we write this in our source file:: +to *logically* add those lines. If we write this in our source file: + +.. include:: /config/typethis.rst + +:: Extend 'give' * 'homage' 'to' noun -> Salute; @@ -762,7 +803,11 @@ players are usually too busy trying to figure out *logical* possibilities.) .. rubric:: FireAt -As usual, we'll first show you the default handler for this action:: +As usual, we'll first show you the default handler for this action: + +.. include:: /config/typethis.rst + +:: [ FireAtSub; if (noun == nothing) @@ -779,7 +824,11 @@ As usual, we'll first show you the default handler for this action:: design practice to reword the message as a statement rather than a question. -Here is the associated grammar:: +Here is the associated grammar: + +.. include:: /config/typethis.rst + +:: Verb 'fire' 'shoot' 'aim' * -> FireAt @@ -848,7 +897,11 @@ cases. pair: FireAt; library action Before leaving the :act:`FireAt` action, we'll add one more piece of -grammar:: +grammar: + +.. include:: /config/typethis.rst + +:: Extend 'attack' replace * noun -> FireAt; @@ -889,7 +942,11 @@ handler is closely based on ``TellSub`` (defined in library file all three checks succeed then ``TalkSub`` need do nothing more; if one or more of them fails then ``TalkSub`` simply... -#. Displays a general "nothing to say" refusal to talk. :: +#. Displays a general "nothing to say" refusal to talk. + + .. include:: /config/typethis.rst + + :: [ TalkSub; if (noun == player) print_ret "Nothing you hear surprises you."; diff --git a/chapters/10.rst b/chapters/10.rst index fd9cbf5..cccb9b7 100644 --- a/chapters/10.rst +++ b/chapters/10.rst @@ -59,6 +59,8 @@ Fade up on: a nondescript city street The game starts with meek John Covarth walking down the street. We set up the game as usual: +.. include:: /config/typethis.rst + .. code-block:: inform !% -SD @@ -232,6 +234,8 @@ normal room, it would seem logical that the phone booth is actually a big box on the sidewalk; therefore we define a :attr:`container` set in the street, which players may enter: +.. include:: /config/typethis.rst + .. code-block:: inform Appliance booth "phone booth" street @@ -387,6 +391,8 @@ every time. There is another solution. We can make the change its value: instead of a string, we write an embedded routine. Here's the (almost) finished room: +.. include:: /config/typethis.rst + .. code-block:: inform Room street "On the street" @@ -414,6 +420,8 @@ Here's the (almost) finished room: The description while inside the booth mentions the sidewalk, which might invite the player to EXAMINE it. No problem: +.. include:: /config/typethis.rst + .. code-block:: inform Appliance "sidewalk" street @@ -431,6 +439,8 @@ result of a LOOK action (which will have to do with the way the café looks from the *inside*); but while we are on the street we need something else to describe it: +.. include:: /config/typethis.rst + .. code-block:: inform Appliance outside_of_cafe "Benny's cafe" street @@ -503,6 +513,8 @@ that it would be neater to handle the actual movement of the player in just one place of our code, because this helps clarity. To achieve this, we redirect the street's :prop:`n_to` property thus: +.. include:: /config/typethis.rst + .. code-block:: inform n_to [; <>; ], @@ -556,6 +568,8 @@ responses. If nothing else, this adds to the general atmosphere, a nicety that many players regard as important. For this mission, we make use of the :obj:`LibraryMessages` object. +.. include:: /config/typethis.rst + .. code-block:: inform Include "Parser"; diff --git a/chapters/11.rst b/chapters/11.rst index ff082ec..84de408 100644 --- a/chapters/11.rst +++ b/chapters/11.rst @@ -55,6 +55,8 @@ define the door object which lies between the café and the toilet. We've mentioned a counter: +.. include:: /config/typethis.rst + .. code-block:: inform Appliance counter "counter" cafe @@ -125,6 +127,8 @@ the player to accomplish this. We've also mentioned some customers. These are treated as NPCs, reacting to our hero’s performance. +.. include:: /config/typethis.rst + .. code-block:: inform Object customers "customers" cafe @@ -327,6 +331,8 @@ in their Captain’s outfit, they’ll be coming from the toilet. As a consequence of all this, we add an :prop:`after` property to the café room object: +.. include:: /config/typethis.rst + .. code-block:: inform Room cafe "Inside Benny's cafe" @@ -452,6 +458,8 @@ and its possible states affect both sides. However, the coding gets a little bit complicated and you''ll have to define routines for most properties: +.. include:: /config/typethis.rst + .. code-block:: inform Object toilet_door "toilet door" @@ -511,6 +519,8 @@ retain the same external name throughout the game -- and the header information method is perfect in that case -- but if it needs to change, it's easy to write a routine as the value of :prop:`short_name`: +.. include:: /config/typethis.rst + .. code-block:: inform Object toilet_door @@ -577,6 +587,8 @@ If a few lines of code can make the life of the player easier, it's worth a shot. Let's provide a few improvements to our toilet door in :prop:`before` and :prop:`after` properties: +.. include:: /config/typethis.rst + .. code-block:: inform before [ ks; @@ -704,6 +716,8 @@ So far, we have the player in front of a locked door leading to the toilet. A dead end? No, the description mentions a scribbled note on its surface. This one should offer no problem: +.. include:: /config/typethis.rst + .. code-block:: inform Object "scribbled note" cafe @@ -744,6 +758,8 @@ ask for it, just as the note explains. Although we'll define Benny in detail throughout the next chapter, here we present a basic definition, largely so that the key has a parent object. +.. include:: /config/typethis.rst + .. code-block:: inform Object benny "Benny" cafe @@ -837,6 +853,8 @@ choose to examine the café from the outside. While it's unlikely that they'll try to examine the toilet room from the outside, it takes very little effort to offer a sensible output just in case: +.. include:: /config/typethis.rst + .. code-block:: inform Object outside_of_toilet "toilet" cafe diff --git a/chapters/12.rst b/chapters/12.rst index 8321823..fbb46cb 100644 --- a/chapters/12.rst +++ b/chapters/12.rst @@ -136,6 +136,8 @@ It seems simple enough. So, following steps one and two, we add those ``pname.h`` right after it. ``Replace`` tells the compiler that we're providing replacements for some standard routines. +.. include:: /config/typethis.rst + .. code-block:: inform Constant Story "Captain Fate"; @@ -162,6 +164,8 @@ added to some of our objects, and which works pretty much like a :prop:`name` property where we have a disambiguation problem. Let’s change the relevant lines for the toilet door and the toilet key: +.. include:: /config/typethis.rst + .. code-block:: inform Object toilet_door @@ -253,6 +257,8 @@ generic form: We have seen some of these actions before. We'll take care of the easier ones: +.. include:: /config/typethis.rst + .. code-block:: inform Attack: @@ -291,6 +297,8 @@ coffee has been paid for, and whether the toilet key has been returned. The solution, yet again (this really is a most useful capability), is more local property variables: +.. include:: /config/typethis.rst + .. code-block:: inform Object benny "Benny" cafe @@ -310,6 +318,8 @@ property, which deals with commands like GIVE THE KEY TO BENNY (in a moment, we'll come to the :act:`Give` action of the :prop:`orders` property, which deals with commands like BENNY, GIVE ME THE KEY): +.. include:: /config/typethis.rst + .. code-block:: inform Give: @@ -385,6 +395,8 @@ demands. The :act:`Give` action in an :prop:`orders` property deals with inputs like ASK BENNY FOR THE KEY or BENNY, GIVE ME THE KEY. The syntax is similar to that of the :prop:`life` property: +.. include:: /config/typethis.rst + .. code-block:: inform orders [; ! handles ASK BENNY FOR X and BENNY, GIVE ME XXX @@ -475,6 +487,8 @@ will. But where? We must revisit the café room object: +.. include:: /config/typethis.rst + .. code-block:: inform Room cafe "Inside Benny's cafe" diff --git a/chapters/13.rst b/chapters/13.rst index a36a32b..4acabcd 100644 --- a/chapters/13.rst +++ b/chapters/13.rst @@ -22,6 +22,8 @@ Additional catering garnish We must not forget a couple of tiny details in the café room: +.. include:: /config/typethis.rst + .. code-block:: inform Object food "Benny's snacks" cafe @@ -45,6 +47,8 @@ We must not forget a couple of tiny details in the café room: And a not-so-trivial object: +.. include:: /config/typethis.rst + .. code-block:: inform Object coffee "cup of coffee" benny @@ -120,6 +124,8 @@ bogged down with details of the room's function or plumbing. There's not a lot about the toilet room and its contents, though there will be some tricky side effects: +.. include:: /config/typethis.rst + .. code-block:: inform Room toilet "Unisex toilet" @@ -195,6 +201,8 @@ will enable us to tell you about Inform's default behaviour when there's no light to see by. However, let's define first the light switch mentioned in the room's description to aid players in their dressing duties. +.. include:: /config/typethis.rst + .. code-block:: inform Appliance light_switch "light switch" toilet @@ -330,6 +338,8 @@ surroundings -- at least until the player decides to close the door. So perhaps it would be a good idea to append a little code to the door object to account for this. A couple of lines in the after property will suffice: +.. include:: /config/typethis.rst + .. code-block:: inform after [ ks; @@ -540,6 +550,8 @@ that the player has picked up at one time in the game; :attr:`scenery` and :attr:`moved`. Here is the reworked ``InScope`` routine. There are a couple of new concepts to look at: +.. include:: /config/typethis.rst + .. code-block:: inform [ InScope person item; @@ -603,6 +615,8 @@ Amazing techicolour dreamcoats This leaves us the clothing items themselves, which will require a few tailored actions. Let's see first the ordinary garments of John Covarth: +.. include:: /config/typethis.rst + .. code-block:: inform Object clothes "your clothes" @@ -708,6 +722,8 @@ change into the hero's suit, after which we'll prevent a change back into ordinary clothes. So now we are dealing with a Captain Fate in full costume: +.. include:: /config/typethis.rst + .. code-block:: inform Object costume "your costume" @@ -749,6 +765,8 @@ All the objects of our game are defined. Now we must add a couple of lines to the ``Initialise`` routine to make sure that the player does not start the game naked: +.. include:: /config/typethis.rst + .. code-block:: inform [ Initialise; @@ -812,6 +830,8 @@ Therefore, we must define a ``DeathMessage`` routine as we did in "William Tell", to write our customised messages and assign them to :var:`deadflag` values greater than 2. +.. include:: /config/typethis.rst + .. code-block:: inform [ DeathMessage; @@ -826,6 +846,8 @@ Finally, we need to extend the existing grammar, to allow for a couple of things. We have already seen that we need a verb CHANGE. We'll make it really simple: +.. include:: /config/typethis.rst + .. code-block:: inform [ ChangeSub; @@ -893,6 +915,8 @@ is perhaps not a major deficiency in our game, but it takes very little to allow Benny to use his default line for *any* undefined input from the player. We need to extend the existing ASK grammar: +.. include:: /config/typethis.rst + .. code-block:: inform Extend 'ask' diff --git a/chapters/14.rst b/chapters/14.rst index 396261f..e9f2a8d 100644 --- a/chapters/14.rst +++ b/chapters/14.rst @@ -85,93 +85,89 @@ player), and we use the placeholders `{obj_id}`, `{var_id}`, 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 -`{statement}`, or any number of `{statements}` enclosed in braces:: - - statement; +`{statement}`, or any number of `{statements}` enclosed in braces: - { statement; statement; ... statement; } + | `{statement};` + | + | `{statement}; {statement}; ... {statement};` 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; - - ; - ; - ; - - <>; - <>; - <>; +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 are sometimes useful:: - - break; - continue; - - do statement_block until (expression) - - for (set_var : loop_while_expression : update_var) statement_block +statements are sometimes useful: - 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 -mostly to do with printing and formatting:: - - box - font - jump - new_line - spaces - string +mostly to do with printing and formatting: + + | `box` + | `font` + | `jump` + | `new_line` + | `spaces` + | `string` In particular, avoid using the deprecated jump statement if you possibly can. diff --git a/chapters/16.rst b/chapters/16.rst index 25e9945..c2543c4 100644 --- a/chapters/16.rst +++ b/chapters/16.rst @@ -378,13 +378,6 @@ change: "OK, Herr Tell, now you're in real trouble. ... -.. 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 tool for novices. If you do use it, be careful: you get a lot of runtime diff --git a/config/typeinfo.rst b/config/typeinfo.rst new file mode 100644 index 0000000..6c7ebb8 --- /dev/null +++ b/config/typeinfo.rst @@ -0,0 +1,6 @@ +.. Explanation of the 'type this' indicator. + +We place the ``--- T Y P E ---`` symbol at the start of game fragments +which you can type in as a part of our working examples. This +differentiates them from other code snippets whose only purpose is to +illustrate some particular feature. diff --git a/config/typethis.rst b/config/typethis.rst new file mode 100644 index 0000000..3076a22 --- /dev/null +++ b/config/typethis.rst @@ -0,0 +1,3 @@ +.. Snippet for indicating that users should type the next bit. + +.. centered:: ``--- T Y P E ---``