From d102cdffefa7d68901d9f6e7d564656270bd0280 Mon Sep 17 00:00:00 2001 From: Glenn Hutchings Date: Sat, 23 Apr 2016 14:33:38 +0100 Subject: [PATCH] Link all the page references to their correct places. --- about.rst | 24 ++++++++--- appendices/c.rst | 2 + appendices/f.rst | 14 ++++++ chapters/01.rst | 24 +++++------ chapters/02.rst | 14 +++--- chapters/03.rst | 11 +++-- chapters/04.rst | 81 +++++++++++++++++++++------------- chapters/05.rst | 40 +++++++++-------- chapters/06.rst | 16 ++++--- chapters/07.rst | 13 +++--- chapters/08.rst | 11 ++--- chapters/09.rst | 18 +++++--- chapters/10.rst | 37 ++++++++-------- chapters/11.rst | 49 ++++++++++----------- chapters/12.rst | 54 +++++++++++------------ chapters/14.rst | 110 +++++++++++++++++++++++++++-------------------- chapters/15.rst | 20 ++++----- conf.py | 2 +- 18 files changed, 308 insertions(+), 232 deletions(-) diff --git a/about.rst b/about.rst index e8024b5..ae816b9 100644 --- a/about.rst +++ b/about.rst @@ -92,9 +92,20 @@ Presentation and style Most of the guide's text appears in this typeface, except where we're using words which are part of the Inform system (like ``print``, ``Include``, ``VerbLib``) or are extracted from one of our games (like ``bird``, -``nest``, ``top_of_tree``). Terms in **bold type** are included in the -glossary -- Appendix G on page 273. We switch to italic type for a -placeholder: for example you should read the Inform statement: +``nest``, ``top_of_tree``). + +.. only:: html + + Terms that are included in the :doc:`Glossary ` appear as + links to that glossary entry. + +.. only:: latex + + Terms that are included in the :doc:`Glossary ` appear in + blue italic. In the PDF version, these are links to the glossary entry. + +We switch to italic type for a placeholder: for example you should read the +Inform statement: :samp:`print "{string}";` @@ -223,7 +234,6 @@ eventually of presenting, the Inform text adventure development system. .. [#play] If you feel confused about IF in general or about this distinction - between writing and playing in particular, try glancing ahead at "Just - what is interactive fiction?" on page 13 and at "How to play an IF game" - on page 209; also, you may find the Ifaq at - http://www.plover.net/~textfire/raiffaq/ifaq/ helpful. + between writing and playing in particular, try glancing ahead at + :doc:`chapters/01` and at :doc:`appendices/a`; also, you may find the + Ifaq at http://www.plover.net/~textfire/raiffaq/ifaq/ helpful. diff --git a/appendices/c.rst b/appendices/c.rst index f7287a6..abbc629 100644 --- a/appendices/c.rst +++ b/appendices/c.rst @@ -28,6 +28,8 @@ Game source code .. literalinclude:: /examples/Tell.inf :language: inform6 +.. _compile-as-you-go: + Compile-as-you-go ================= diff --git a/appendices/f.rst b/appendices/f.rst index e1fd4b0..372dc56 100644 --- a/appendices/f.rst +++ b/appendices/f.rst @@ -198,6 +198,8 @@ Library variables `wn` The input stream word number, counting from 1. +.. _library-routines: + Library routines ================ @@ -365,6 +367,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. +.. _object-props: + Object properties ================= @@ -660,6 +664,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. +.. _object-attrs: + Object attributes ================= @@ -760,6 +766,8 @@ Object attributes `worn` For a `clothing` object: is being worn. +.. _entry-points: + Optional entry points ===================== @@ -834,6 +842,8 @@ These routines, if you supply them, are called when shown. `UnknownVerb()` Called when an unusual verb is encountered. +.. _group-1-actions: + Group 1 actions =============== @@ -889,6 +899,8 @@ and the debug tools. `XTree` "`TREE`" =============== =================================================== +.. _group-2-actions: + Group 2 actions =============== @@ -951,6 +963,8 @@ Group 2 actions usually work, given the right circumstances. `Wear` "`DON`", "`PUT ON`", "`WEAR`" ============= ============================================================= +.. _group-3-actions: + Group 3 actions =============== diff --git a/chapters/01.rst b/chapters/01.rst index 119904c..fb85370 100644 --- a/chapters/01.rst +++ b/chapters/01.rst @@ -85,9 +85,8 @@ of a familiar folk tale. And now an extract from the same tale, this time in the form of a tiny text adventure game. If you're new to interaction with text adventures you'll -find some general instructions in "How to play an IF game" on page 209, and -you can see a complete transcript of the game in the "William Tell" story -on page 219:: +find some general instructions in :doc:`/appendices/a`, and you can see a +complete transcript of the game in :doc:`/appendices/c`. :: A street in Altdorf The narrow street runs north towards the town square. Local folk are @@ -218,16 +217,15 @@ Some of the more obvious differences are highlighted by these questions: * How do I work this thing? Whereas the presence of Helga is an elaboration of the folk tale, the - shooting of the arrow (it's in the transcript in "William Tell" story - on page 219, not in the extract above) illustrates the opposite - principle: simplification. The tale builds dramatic tension by - describing each step as Wilhelm prepares to shoot the apple. That's - OK; he's been an archer all his life, and knows how to do it. You, on - the other hand, probably know little about archery, and shouldn't be - expected to guess at the process and vocabulary. Let's hope you know - that you need to shoot at the apple -- and that's all it takes. The - game explains what was involved, but doesn't force you through each - mundane step. + shooting of the arrow (it's in the transcript in :doc:`/appendices/c`, + not in the extract above) illustrates the opposite principle: + simplification. The tale builds dramatic tension by describing each + step as Wilhelm prepares to shoot the apple. That's OK; he's been an + archer all his life, and knows how to do it. You, on the other hand, + probably know little about archery, and shouldn't be expected to guess + at the process and vocabulary. Let's hope you know that you need to + shoot at the apple -- and that's all it takes. The game explains what + was involved, but doesn't force you through each mundane step. Of course, all of these are generalisations, not universal truths; you could find fine works of IF which contradict each observation. However, diff --git a/chapters/02.rst b/chapters/02.rst index 800190c..ee0b5b2 100644 --- a/chapters/02.rst +++ b/chapters/02.rst @@ -61,8 +61,8 @@ You will never need to look at it in the form produced by the compiler:: 0000000000000000000000000000168F000000000000010200000000362E3231 ... -but, as you'll notice from the full transcript in "William Tell" story on -page 219, the player will see the following:: +but, as you'll notice from the full transcript in :doc:`/appendices/c`, the +player will see the following:: The place: Altdorf, in the Swiss canton of Uri. The year is 1307, at which time Switzerland is under rule by the Emperor Albert of @@ -99,8 +99,8 @@ no fancy formatting features, no bold or italics or font control, no embedded graphics; it simply enables you to type lines of text, which is exactly what's needed to create an IF game. -If you look at the game source on the previous page, or in the "William -Tell" story on page 219, you'll notice ``Include "Parser";`` and ``Include +If you look at the game source on the previous page, or in +:doc:`/appendices/c`, you'll notice ``Include "Parser";`` and ``Include "VerbLib";`` a few lines down from the top of the file. These are instructions to the Inform compiler to "include" -- that is, to merge in the contents -- of files called ``Parser.h`` and ``VerbLib.h``. These are @@ -141,6 +141,8 @@ for the "Software" section. However, if you're using a PC or a Mac, you'll find it easier to download a complete package containing everything that you need to get started. +.. _inform-windows: + Inform on an IBM PC (running Microsoft Windows) =============================================== @@ -350,6 +352,8 @@ the file -- and it compiles there and then. You can also run the interpreter with similar ease. The convenience of doing this far outweighs the small amount of time needed to obtain and configure TextPad. +.. _inform-apple: + Inform on an Apple Macintosh (running OS X) =========================================== @@ -724,7 +728,7 @@ write a Z-code file. *Do not worry about this*: the rules are easy to learn, but just as easy to break, and all Inform designers inadvertently do so on a regular basis. There's some additional information about dealing with these mistakes, and about controlling how the compiler behaves, in -"Compiling your game" on page 189. +:doc:`15`. .. rubric:: More about the interpreter diff --git a/chapters/03.rst b/chapters/03.rst index 8dd586a..061810b 100644 --- a/chapters/03.rst +++ b/chapters/03.rst @@ -123,12 +123,11 @@ that we design will start out like this. Follow these steps: containing two files: ``Heidi.inf`` and either ``Heidi.bat`` or ``Heidi.command``. -#. Compile the source file ``Heidi.inf``; refer back to "Inform on an IBM - PC (running Microsoft Windows)" on page 19 or "Inform on an Apple - Macintosh (running OS X)" on page 24 for guidance. If the compilation - works, a story file ``Heidi.z5`` appears in the folder. If the - compilation *doesn't* work, you've probably made a typing mistake; check - everything until you find it. +#. Compile the source file ``Heidi.inf``; refer back to + :ref:`inform-windows` or :ref:`inform-apple` for guidance. If the + compilation works, a story file ``Heidi.z5`` appears in the folder. If + the compilation *doesn't* work, you've probably made a typing mistake; + check everything until you find it. #. You can run the story file in your Inform interpreter; you should see this (except that the Serial number will be different -- it's based on diff --git a/chapters/04.rst b/chapters/04.rst index 8958b59..a1a05ad 100644 --- a/chapters/04.rst +++ b/chapters/04.rst @@ -22,9 +22,10 @@ oing through the design of our first game in the previous chapter has introduced all sorts of Inform concepts, often without giving you much detail about what's been happening. So let's review some of what we've learnt so far, in a slightly more organised fashion. We'll talk about -"Constants and variables" on page 49, "Object definitions" on page 50, -"Object relationships -- the object tree" on page 52, "Things in quotes" on -page 55, and "Routines and statements" on page 56. +:ref:`const-var`, :ref:`object-defs`, :ref:`object-tree`, +:ref:`things-in-quotes` and :ref:`routines-statements`. + +.. _const-var: Constants and variables ======================= @@ -32,7 +33,8 @@ Constants and variables Superficially similar, constants and variables are actually very different beasts. -.. rubric:: Constants +Constants +--------- A :term:`constant` is a name to which a value is given once and once only; you can't later use that name to stand for a different value. Think of it @@ -51,7 +53,8 @@ and as a number:: Those two examples represent the most common ways in which constants are used in Inform. -.. rubric:: Variables +Variables +--------- A :term:`variable` is a name to which a value is given, but that value can be changed to a different one at any time. Think of it as a blackboard on @@ -76,9 +79,10 @@ to reset the value of the ``location`` variable to the to reset the value of the ``deadflag`` variable to 2. -Later, we'll talk about the :term:`local variable` (see "Routines" on -page 179) and about using object properties as variables (see "Objects" on -page 177). +Later, we'll talk about the :term:`local variable` (see :ref:`routines`) +and about using object properties as variables (see :ref:`objects`). + +.. _object-defs: Object definitions ================== @@ -111,7 +115,8 @@ in between are three major blocks of information: * the word ``with`` introduces the object's :term:`properties`; * the word ``has`` introduces the object's :term:`attributes`. -.. rubric:: Object headers +Object headers +-------------- An object header comprises up to three items, all optional: @@ -159,9 +164,10 @@ An object header comprises up to three items, all optional: ... We don't use the arrows method in this guide, though we do describe - how it works in "Setting up the object tree" on page 185. + how it works in :ref:`setting-up-tree`. -.. rubric:: Object properties +Object properties +----------------- An object's property definitions are introduced by the ``with`` keyword. An object can have any number of properties, and they can be defined in any @@ -187,18 +193,18 @@ characters in double quotes; the value associated with this ``e_to`` property is the internal identity of an object; the ``name`` property is a bit unusual -- its value is a list of dictionary words, each in single quotes; the ``each_turn`` property has a value which is an :term:`embedded -routine` (see "Embedded routines" on page 58). The only other type of -value which is commonly found is a simple number; for example:: +routine` (see :ref:`embedded-routines`). The only other type of value +which is commonly found is a simple number; for example:: capacity 10, In all, the library defines around forty-eight standard properties -- like ``name`` and ``each_turn`` -- which you can associate with your objects; -there's a complete list in "Object properties" on page 266. And in -"William Tell: in his prime" on page 91 we show you how to invent your own -property variables. +there's a complete list in :ref:`object-props`. And in :doc:`08` we show +you how to invent your own property variables. -.. rubric:: Object attributes +Object attributes +----------------- An object's attribute list is introduced by the ``has`` keyword. An object can have any number of attributes, and they can be listed in any order, @@ -223,10 +229,11 @@ Each of those answers a question: Is this object a container? Does it provide light? and so on. If the attribute is present then the answer is Yes; if the attribute isn't present, the answer is No. -The library defines around thirty standard attributes, listed in "Object -attributes" on page 269. Although you *can* devise additional attributes --- see "Common properties and attributes" on page 185 -- in practice you -seldom need to. +The library defines around thirty standard attributes, listed in +:ref:`object-attrs`. Although you *can* devise additional attributes -- +see :ref:`common-props` -- in practice you seldom need to. + +.. _object-tree: Object relationships -- the object tree ======================================= @@ -363,14 +370,17 @@ given object with the ``parent``, ``child`` and ``children`` routines, and this is one feature that you will be using frequently. There are also other routines associated with the object tree, to help you keep track of the objects or move them around. We'll see them one by one in the next -chapters. For a quick summary, see "Objects" on page 177. +chapters. For a quick summary, see :ref:`objects`. + +.. _things-in-quotes: Things in quotes ================ Inform makes careful distinction between double and single quotes. -.. rubric:: Double quotes +Double quotes +------------- Double quotes ``"..."`` surround a :term:`string` -- a letter, a word, a paragraph, or almost any number of characters -- which you want the @@ -413,7 +423,8 @@ and as the value of an object ``description`` property:: Later, you'll find that they're also very common in ``print`` statements. -.. rubric:: Single quotes +Single quotes +------------- Single quotes ``'...'`` surround a :term:`dictionary word`. This has to be a single word -- no spaces -- and generally contains only letters (and @@ -436,15 +447,18 @@ and indeed that's just about the only place where they commonly occur. You'll save yourself a lot of confusion by remembering the distinction: Double quotes for Output, Single quotes for Input (DOSI). +.. _routines-statements: + Routines and statements ======================= A routine is a collection of statements, which are performed (or we often say "are executed") at run-time by the interpreter. There are two types of routine, and about two dozen types of statement (there's a complete list in -"Statements" on page 174; see also "Inform language" on page 257). +:ref:`statements`; see also :doc:`/appendices/e`). -.. rubric:: Statements +Statements +---------- A :term:`statement` is an instruction telling the interpreter to perform a particular task -- to "do something" -- while the game is being played. A @@ -491,7 +505,10 @@ talk about these other possibilities later. For now, just remember that the only place where you'll find statements are within standalone routines and embedded routines. -.. rubric:: Standalone routines +.. _standalone-routines: + +Standalone routines +------------------- A :term:`standalone routine` is a series of statements, collected together and given a name. When the routine is "called" -- by its given name -- @@ -530,7 +547,10 @@ call. routine *is* called, by the Inform library, right at the start of a game. -.. rubric:: Embedded routines +.. _embedded-routines: + +Embedded routines +----------------- An :term:`embedded routine` is much like a standalone routine, though it doesn't have a name and doesn't end in a semicolon. This is the one that @@ -567,9 +587,8 @@ embedded routines, each designed to perform a task which is appropriate for the property whose value it is; we'll also see that it is possible to call an embedded routine yourself, using an ``obj_id.property()`` syntax -- in this example, we could call the routine by writing ``branch.each_turn()``. -There's more about these topics in "Routines and arguments" on page 67, "A -diversion: working with routines" on page 104 and in "Routines" on -page 179. +There's more about these topics in :ref:`routines-args`, +:ref:`working-with-routines` and in :ref:`routines`. That ends our review of the ground covered in our first game. We'll have more to say about most of this later, but we're trying not to overload you diff --git a/chapters/05.rst b/chapters/05.rst index 1c0c623..c730e1b 100644 --- a/chapters/05.rst +++ b/chapters/05.rst @@ -304,15 +304,16 @@ fortunately all of that complexity is hidden: there's a standard :term:`library routine` to do the job, not one that we've written, but one that's provided as part of the Inform system. -You'll remember that, when we first mentioned routines (see "Standalone -routines" on page 57), we used the example of ``Initialise()`` and said -that "the routine's name followed by opening and closing parentheses is all -that it takes to call a routine". That was true for ``Initialise()``, but -not quite the whole story. To move the player character, we've got to -specify where we want her to go, and we do that by supplying the internal -ID of the destination room within the opening and closing parentheses. -That is, instead of just ``PlayerTo()`` we call ``PlayerTo(top_of_tree)``, -and we describe ``top_of_tree`` as the routine's :term:`argument`. +You'll remember that, when we first mentioned routines (see +:ref:`standalone-routines`), we used the example of ``Initialise()`` and +said that "the routine's name followed by opening and closing parentheses +is all that it takes to call a routine". That was true for +``Initialise()``, but not quite the whole story. To move the player +character, we've got to specify where we want her to go, and we do that by +supplying the internal ID of the destination room within the opening and +closing parentheses. That is, instead of just ``PlayerTo()`` we call +``PlayerTo(top_of_tree)``, and we describe ``top_of_tree`` as the routine's +:term:`argument`. Although we've moved the player character to another room, we're still in the middle of the intercepted ``Climb`` action. As previously, we need to @@ -484,7 +485,8 @@ when you're telling the player "sorry, you can't do that". The new topics that we've encountered here include these: -.. rubric:: Object properties +Object properties +----------------- Objects can have a ``before`` property -- if there is one, the interpreter looks at it *before* performing an action which in some way involves that @@ -515,11 +517,14 @@ explicitly listed:: in_to "It's such a lovely day -- much too nice to go inside.", cant_go "The only path lies to the east.", -.. rubric:: Routines and arguments +.. _routines-args: + +Routines and arguments +---------------------- The library includes a number of useful routines, available to perform -certain common tasks if you require them; there's a list in "Library -routines" on page 264. We used the ``PlayerTo`` routine, which moves the +certain common tasks if you require them; there's a list in +:ref:`library-routines`. We used the ``PlayerTo`` routine, which moves the player character from her current room to another one -- not necessarily adjacent to the first room. @@ -540,7 +545,8 @@ a second argument:: In this example, the effect of the ``1`` is to prevent the description being displayed. -.. rubric:: Statements +Statements +---------- We encountered several new statements: @@ -609,11 +615,11 @@ PUT NEST ON BRANCH PutOn nest branch The value ``nothing`` is a built-in constant (like ``true`` and ``false``) which means, well, there isn't any object to refer to. There's a list of -standard library actions in "Group 1 actions" on page 270, "Group 2 -actions" on page 271 and "Group 3 actions" on page 271. +standard library actions in :ref:`group-1-actions`, :ref:`group-2-actions` +and :ref:`group-3-actions`. We've now reached the end of our first game. In these three chapters we've shown you the basic principles on which almost all games are based, and introduced you to many of the components that you'll need when creating more interesting IF. We suggest that you take one last look at the source -code (see "Heidi" story on page 213), and then move on to the next stage. +code (see :doc:`/appendices/b`), and then move on to the next stage. diff --git a/chapters/06.rst b/chapters/06.rst index 902ff0b..98224c7 100644 --- a/chapters/06.rst +++ b/chapters/06.rst @@ -204,7 +204,7 @@ The game won't compile in this state, because it contains references to objects which we haven't yet defined. In any case, we don't intend to build up the game in layers as we did last time, but rather to talk about it in logically related chunks. To see (and if you wish, to type) the -complete source, go to "William Tell" story on page 219. +complete source, go to :doc:`/appendices/c`. Object classes ============== @@ -339,7 +339,10 @@ You'll notice that, if an object has no block of attributes, the semicolon which terminates its definition simply moves to the end of its last property. -.. rubric:: A class for props +.. _props-class: + +A class for props +----------------- 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 @@ -434,7 +437,8 @@ object like Heidi's ``tree`` and ``cottage``, is to support EXAMINE for increased realism, while clearly hinting to players that trying other verbs would be a waste of time. -.. rubric:: A class for furniture +A class for furniture +--------------------- The last class for now -- we'll talk about the ``Arrow`` and ``NPC`` classes in the next chapter -- is for furniture-like objects. If you label @@ -475,6 +479,6 @@ probably reuse them in your next game. Now that most of our class definitions are in place, we can get on with defining some real rooms and objects. First, though, if you're typing in the "William Tell" game as you read through the guide, you'd probably like -to check that what you've entered so far is correct; "Compile-as-you-go" on -page 233 explains how to compile the game in its current -- incomplete -- -state. +to check that what you've entered so far is correct; +:ref:`compile-as-you-go` explains how to compile the game in its current -- +incomplete -- state. diff --git a/chapters/07.rst b/chapters/07.rst index 8289c38..9e928a3 100644 --- a/chapters/07.rst +++ b/chapters/07.rst @@ -141,6 +141,8 @@ hasnt visited)``, you'll have to change that as well. Worse, if you *forget* to change it, the game will still work -- but not in the way you'd intended, and the resulting bug will be quite difficult to track down. +.. _adding-props: + Adding some props ================= @@ -259,6 +261,8 @@ true if *any* of those individual tests is true. And in the third example we introduce the ``or`` keyword, which is a more succinct way of achieving exactly the same result. +.. _possessions: + The player's possessions ======================== @@ -492,7 +496,7 @@ interaction. Additionally, a new ``life`` property -- very similar to ``before`` -- can be defined to intercept them. Here we use it to trap speech-related commands 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 "Verbs, verbs, verbs" on page 111). +TALK verb (which we describe in :ref:`verbs`). Based on the NPC class we've created, here's Helga:: @@ -538,8 +542,7 @@ scored; when it changes like this, the interpreter tells the player that "Your score has just gone up by one point". There are also ``life`` and ``times_spoken_to`` properties (which we'll -talk about in "William Tell: the end is nigh" on page 103) and an -``initial`` property. +talk about in :doc:`09`) and an ``initial`` property. ``initial`` is used when the interpreter is describing a room and listing the objects initial you can see there. If we *didn't* define it, you'd get @@ -702,5 +705,5 @@ neatly:: We've done a lot of scene-setting, but the real action is still to come. Next, it's time to define the town square, and create a confrontation between Wilhelm and the vogt's soldiers. (But first, see again -"Compile-as-you-go" on page 233 if you're typing in the game as you read -through the guide.) +:ref:`compile-as-you-go` if you're typing in the game as you read through +the guide.) diff --git a/chapters/08.rst b/chapters/08.rst index 5ee56f8..cf555a3 100644 --- a/chapters/08.rst +++ b/chapters/08.rst @@ -23,6 +23,8 @@ chapter we define the square's constituent rooms and deal with Wilhelm's approach to the hat on the pole -- does he salute it, or does he remain proudly defiant? +.. _south-side: + The south side of the square ============================ @@ -81,9 +83,8 @@ The obnoxious soldiers are also implemented very sketchily; they need to be there, but they don't do much. Their most interesting characteristic is probably that they trap two actions -- ``FireAt`` and ``Talk`` -- which are *not* part of the library, but instead new actions that we've defined -specially for this game. We'll talk about those actions in "Verbs, verbs, -verbs" on page 111, at which time the role of this ``before`` property will -make more sense. +specially for this game. We'll talk about those actions in :ref:`verbs`, +at which time the role of this ``before`` property will make more sense. The middle of the square ======================== @@ -208,8 +209,8 @@ that the salute was "gratefully" received. Creating new property variables like this -- at the drop of a hat, as it were -- is the recommended approach, but it isn't the only possibility. - We briefly mention some alternative approaches in "Reading other - people's code" on page 181. + We briefly mention some alternative approaches in + :ref:`reading-other-code`. Back to the ``mid_square`` room. We've said that we need to detect Wilhelm trying to leave this room, which we can do by trapping the ``Go`` action in diff --git a/chapters/09.rst b/chapters/09.rst index 448a152..797b343 100644 --- a/chapters/09.rst +++ b/chapters/09.rst @@ -67,6 +67,8 @@ a complex test, and one that we'll be making in several places, it's sensible to write a routine to do the job. Which we'll do shortly -- but first, a general introduction to working with routines. +.. _working-with-routines: + A diversion: working with routines ================================== @@ -198,9 +200,9 @@ Remember that: ``rfalse`` statement, or by the the ``]`` marking the routine's end (in which case the default STEF rule applies: Standalone routines return True, Embedded routines return False). We gave this example of an - embedded routine in "Adding some props" on page 81. The ``return - false`` statement is redundant: we could remove it without affecting the - routine's behaviour, because the ``]`` acts like a ``return false``:: + embedded routine in :ref:`adding-props`. The ``return false`` statement + is redundant: we could remove it without affecting the routine's + behaviour, because the ``]`` acts like a ``return false``:: found_in [; if (location == street or below_square or south_square or @@ -231,8 +233,8 @@ Return value is important Return value doesn't matter ========================= =========================== For full details on which library property values can be embedded routines, -and which return values are significant, see "Object properties" on page -266 and Appendix §A2 of the *Inform Designer's Manual*. +and which return values are significant, see :ref:`object-props` and +Appendix §A2 of the *Inform Designer's Manual*. Return to the marketplace ========================= @@ -481,6 +483,8 @@ And with that, we've defined all of the objects. In doing so, we've added a whole load of new nouns and adjectives to the game's dictionary, but no verbs. That's the final task. +.. _verbs: + Verbs, verbs, verbs =================== @@ -862,5 +866,5 @@ falling back on the embarrassing silences implied by "You can't think of anything to say". That's the end of our little fable; you'll find a transcript and the full -source in "William Tell" story on page 219. And now, it's time to meet -- -Captain Fate! +source in :doc:`/appendices/c`. And now, it's time to meet -- Captain +Fate! diff --git a/chapters/10.rst b/chapters/10.rst index 1f1d4b2..d8b3218 100644 --- a/chapters/10.rst +++ b/chapters/10.rst @@ -32,8 +32,7 @@ information in logical didactic chunks, defining some of the objects minimally at first and then adding complexity as need arises. Again, this means that you won't be able to compile for testing purposes after the addition of every code snippet, so, if you're typing in the game as -you read, you’ll need to check the advice in "Compile-as-you-go" on page -255. +you read, you’ll need to check the advice in :ref:`compile-as-you-go`. A lot of what goes into this game we have already seen; you may deduce from this that the game design business is fairly repetitious and that @@ -496,20 +495,18 @@ this, we redirect the street's ``n_to`` property thus: n_to [; <>; ], -You may think that this is unnecessary madness, but a word to the wise: -in a large game, you want action handling going on just in one place -when possible, because it will help you to keep track of where things -are a-happening if something goes *ploof* (as, believe us, it will; see -"Debugging your game" on page 197). You don't need to be a -perfectionist, just cautious. - -A booth in this kind of situation is an open invitation for the player -to step inside and try to change into Captain Fate's costume. We won't -let this happen -- the player isn't Clark Kent, after all; later we'll -explain how we forbid this action -- and that will force the player to -go inside the café, looking for a discreet place to disrobe; but first, -let''s freeze John Covarth outside Benny''s and reflect about a -fundamental truth. +You may think that this is unnecessary madness, but a word to the wise: in +a large game, you want action handling going on just in one place when +possible, because it will help you to keep track of where things are +a-happening if something goes *ploof* (as, believe us, it will; see +:doc:`16`). You don't need to be a perfectionist, just cautious. + +A booth in this kind of situation is an open invitation for the player to +step inside and try to change into Captain Fate's costume. We won't let +this happen -- the player isn't Clark Kent, after all; later we'll explain +how we forbid this action -- and that will force the player to go inside +the café, looking for a discreet place to disrobe; but first, let's freeze +John Covarth outside Benny's and reflect about a fundamental truth. A hero is not an ordinary person ================================ @@ -668,7 +665,7 @@ the default messages, but that wouldn't be a sound practice, because your library file will probably not be right for the next game. Use of the ``LibraryMessages`` object is strongly advised. -If you're typing in the game, you'll probably want to read the brief -section on "Compile-as-you-go" on page 255 prior to performing a test -compile. Once everything's correct, it’s time that our hero entered that -enticing café. +If you're typing in the game, you'll probably want to read the brief +section on :ref:`compile-as-you-go` prior to performing a test compile. +Once everything's correct, it’s time that our hero entered that enticing +café. diff --git a/chapters/11.rst b/chapters/11.rst index 92ce631..ef71004 100644 --- a/chapters/11.rst +++ b/chapters/11.rst @@ -21,6 +21,8 @@ with lunchtime customers. We'll try to conjure up some appropriate images, but the main focus of the room isn't the decor: it's the door leading to the toilet -- and, perhaps, privacy? +.. _homely-atmos: + A homely atmosphere =================== @@ -102,12 +104,12 @@ action`. .. note:: - in "William Tell" we defined the ``quiver``, way back in "The - player's possessions" on page 83, as an ``open container``. As things - stand, the player can put *any* held object, however inappropriate, - into it. We could have trapped the Receive action to ensure that - arrows are the only acceptable contents (recollect that ``~~``, to be - read as "not", turns true into false and vice versa): + in "William Tell" we defined the ``quiver``, way back in + :ref:`possessions`, as an ``open container``. As things stand, the player + can put *any* held object, however inappropriate, into it. We could have + trapped the Receive action to ensure that arrows are the only acceptable + contents (recollect that ``~~``, to be read as "not", turns true into + false and vice versa): .. code-block:: inform @@ -503,11 +505,11 @@ adjectives -- perhaps a shining/flickering/fading/useless lantern. .. note:: - what's displayed if there isn't an external name in an object's - header? If you've read the section "Compile-as-you-go" on page 233, - you'll recall that the interpreter simply uses the internal - identifier within parentheses; that is, with no external name and no - ``short_name`` property, we might see: + what's displayed if there isn't an external name in an object's header? + If you've read the section :ref:`compile-as-you-go`, you'll recall that + the interpreter simply uses the internal identifier within parentheses; + that is, with no external name and no ``short_name`` property, we might + see: .. code-block:: inform @@ -753,19 +755,18 @@ key while it’s in Benny’s pockets, we define a ``before`` property. "Benny is trusting you to look after that key."; ]; -All of the ``before`` properties that we've so far created have -contained one or more labels specifying the actions which they are to -intercept; you'll remember that in "William Tell" we introduced the -``default`` action (see "A class for props" on page 74) to mean "any -value not already catered for". There's one of those labels here, for -the Drop action, but that's preceded by a piece of code that will be -executed at the start of *every* action directed at the key. If it’s -still in Benny’s possession, we display a polite refusal; if the player -has it then we prevent careless disposal; otherwise, the action -continues unhindered. - -(In fact, the hat-on-a-pole ``Prop`` introduced on page 91 had this -all-exclusive ``before`` property: +All of the ``before`` properties that we've so far created have contained +one or more labels specifying the actions which they are to intercept; +you'll remember that in "William Tell" we introduced the ``default`` action +(see :ref:`props-class`) to mean "any value not already catered +for". There's one of those labels here, for the Drop action, but that's +preceded by a piece of code that will be executed at the start of *every* +action directed at the key. If it’s still in Benny’s possession, we display +a polite refusal; if the player has it then we prevent careless disposal; +otherwise, the action continues unhindered. + +(In fact, the hat-on-a-pole ``Prop`` introduced in :ref:`south-side` had +this all-exclusive ``before`` property: .. code-block:: inform diff --git a/chapters/12.rst b/chapters/12.rst index 4e8654a..d00131f 100644 --- a/chapters/12.rst +++ b/chapters/12.rst @@ -64,15 +64,14 @@ there are rules about where exactly this Include should be placed in your source code. It is not unusual to find other suggestions and warnings. -To help us out of the disambiguation problem with the word TOILET, we -are going to use Neil Cerutti's extension ``pname.h``, which is designed -for situations precisely like this. First, we follow the link to the IF -archive and download the compressed file ``pname.zip``, which contains -two more files: ``pname.h`` and ``pname.txt``. We place these files in -the folder where we are currently developing our game or, if using the -environment we proposed in "Tools of the trade" on page 17, in the -``Inform\Lib\Contrib`` folder. The text file offers instructions about -installation and usage. Here we find a warning: +To help us out of the disambiguation problem with the word TOILET, we are +going to use Neil Cerutti's extension ``pname.h``, which is designed for +situations precisely like this. First, we follow the link to the IF archive +and download the compressed file ``pname.zip``, which contains two more +files: ``pname.h`` and ``pname.txt``. We place these files in the folder +where we are currently developing our game or, if using the environment we +proposed in :doc:`02`, in the ``Inform\Lib\Contrib`` folder. The text file +offers instructions about installation and usage. Here we find a warning: This version of pname.h is recommended for use only with version 6/10 of the Inform Library. @@ -340,25 +339,24 @@ statement as shorthand for: if (noun == clothes) { whatever }; !... -We won't let players give away their clothes or their costume (yes, an -improbable action, but you never know). The toilet key and the coin are -successfully transferred. The property ``key_not_returned`` will be set -to true when we receive the toilet key from Benny (we have not coded -that bit yet), and now, when we give it back, it's reset to ``false``. -The ``move`` statement is in charge of the actual transfer of the object -from the player's inventory to Benny, and we finally display a -confirmation message. With the coin, we find a new statement: -``remove``. This extracts the object from the object tree, so that it -now has no parent. The effect is to make it disappear from the game -(though you are not destroying the object permanently -- and indeed you -could return it to the object tree using the ``move`` statement); as far -as the player is concerned, there isn’t a COIN to be found anywhere. The -``coffee_not_paid`` property will be set to true when Benny serves us -the cup of coffee (again, we’ll see that in a moment); now we reset it -to ``false``, which liberates the player from debt. This culminates with -the ``"..."`` print-and-return statement, telling the player that the -action was successful. In passing, remember that in "A homely -atmosphere" on page 131 we defined the counter such that PUT KEY ON +We won't let players give away their clothes or their costume (yes, an +improbable action, but you never know). The toilet key and the coin are +successfully transferred. The property ``key_not_returned`` will be set to +true when we receive the toilet key from Benny (we have not coded that bit +yet), and now, when we give it back, it's reset to ``false``. The ``move`` +statement is in charge of the actual transfer of the object from the +player's inventory to Benny, and we finally display a confirmation +message. With the coin, we find a new statement: ``remove``. This extracts +the object from the object tree, so that it now has no parent. The effect +is to make it disappear from the game (though you are not destroying the +object permanently -- and indeed you could return it to the object tree +using the ``move`` statement); as far as the player is concerned, there +isn’t a COIN to be found anywhere. The ``coffee_not_paid`` property will be +set to true when Benny serves us the cup of coffee (again, we’ll see that +in a moment); now we reset it to ``false``, which liberates the player from +debt. This culminates with the ``"..."`` print-and-return statement, +telling the player that the action was successful. In passing, remember +that in :ref:`homely-atmos` we defined the counter such that PUT KEY ON COUNTER is automatically translated into GIVE KEY TO BENNY . Why move the key to Benny but remove the coin instead? Once players diff --git a/chapters/14.rst b/chapters/14.rst index f943789..fa4f516 100644 --- a/chapters/14.rst +++ b/chapters/14.rst @@ -1,6 +1,6 @@ -====================== -Some last lousy points -====================== +======================== + Some last lousy points +======================== .. only:: html @@ -20,17 +20,15 @@ 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 "Reading other people's code" on page 181, about a -few ways of doing things that we've chosen not to tell you about, but -which you're quite likely to encounter if you look at Inform code -written by other designers. +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 +likely to encounter if you look at Inform code written by other designers. The tone here is perhaps a little dry, but trust us: in walking this dusty ground we touch on just about everything that is fundamental in your overall understanding of Inform. And as always, the *Inform Designer's Manual* provides rounder and more comprehensive coverage. - Expressions =========== @@ -83,6 +81,7 @@ player), and we use the placeholders ``obj_id``, ``var_id``, used (except that a routine's local variables are not visible outside that routine). +.. _statements: Statements ========== @@ -105,7 +104,8 @@ use the placeholder ``statement_block`` to represent either a single { statement; statement; ... statement; } -.. rubric:: Statements that we've met +Statements that we've met +------------------------- Our games have used these statements, about half of the Inform possibilities: @@ -152,8 +152,8 @@ possibilities: <>; <>; - -.. rubric:: Statements that we've not met +Statements that we've not met +----------------------------- Although our example games haven't needed to use them, these looping statements are sometimes useful: @@ -184,7 +184,8 @@ mostly to do with printing and formatting: In particular, avoid using the deprecated jump statement if you possibly can. -.. rubric:: Print rules +Print rules +----------- In ``print`` and ``print_ret`` statements, each ``value`` can be: @@ -217,7 +218,8 @@ what to do at compile-time, while the source file is being translated into Z-code. By convention it's given an initial capital letter (though the compiler doesn't enforce this) and always ends with a semicolon. -.. rubric:: Directives that we've met +Directives that we've met +------------------------- We've used all of these directives; note that for ``Class``, ``Extend``, ``Object`` and ``Verb`` the full supported syntax is more sophisticated @@ -269,7 +271,8 @@ than the basic form presented here: #Ifdef any_id; ... #Endif; -.. rubric:: Directives that we've not met +Directives that we've not met +----------------------------- There's only a handful of useful directives which we haven't needed to use: @@ -306,6 +309,8 @@ but there's a whole load which are of fairly low importance for now: System_file Zcharacter +.. _objects: + Objects ======= @@ -314,7 +319,8 @@ represent the capabilities and current status of some specific component of the model world. Full variables are called properties; simpler two-state variables are attributes. -.. rubric:: Properties +Properties +---------- The library defines around forty-eight standard property variables (such as ``before`` or ``name``), but you can readily create further ones just @@ -354,13 +360,15 @@ and you can test whether an object definition includes a given property: (obj_id provides property) ! is true or false +.. _routines: Routines ======== Inform provides standalone routines and embedded routines. -.. rubric:: Standalone routines +Standalone routines +------------------- Standalone routines are defined like this: @@ -374,7 +382,8 @@ and called like this: routine_id() -.. rubric:: Embedded routines +Embedded routines +----------------- These are embedded as the value of an object's property: @@ -390,7 +399,8 @@ and are usually called automatically by the library, or manually by: obj_id.property() ! everywhere -.. rubric:: Arguments and local variables +Arguments and local variables +----------------------------- Both types of routine support up to fifteen local variables -- variables which can be used only by the statements within the routine, and which @@ -416,8 +426,8 @@ Although it works, this technique is rarely used with embedded routines, because there is no mechanism for the library to supply argument values when calling the routine. - -.. rubric:: Return values +Return values +------------- Every routine returns a single value, which is supplied either explicitly by some form of return statement: @@ -468,9 +478,8 @@ though legal, does nothing useful whatsoever): switch (Max(3,y)) { ... - -.. rubric:: Library routines versus entry points - +Library routines versus entry points +------------------------------------ A library routine is a standard routine, included within the library files, which you can optionally call from your source file if you @@ -506,9 +515,9 @@ And this, the only mandatory one: Initialise() -There are full lists in "Library routines" on page 264 and "Optional -entry points" on page 270. +There are full lists in :ref:`library-routines` and :ref:`entry-points`. +.. _reading-other-code: Reading other people's code =========================== @@ -524,7 +533,8 @@ to find a style that suits you and, this is the important bit, be *consistent* about its use. In this section, we highlight some of the more obvious differences which you may encounter. -.. rubric:: Code layout +Code layout +----------- Every designer has his or her own style for laying out their source code, and they're all worse than the one you adopt. Inform's flexibility @@ -590,7 +600,8 @@ though that second ``else`` looks suspicious: We hope you'll agree that the result was worth the tiny extra effort. Code gets written once; it gets read dozens and dozens of times. -.. rubric:: Shortcuts +Shortcuts +--------- There are a few statement shortcuts, some more useful than others, which you'll come across. @@ -731,7 +742,8 @@ you'll come across. if (--MyVar == 7) ... if (MyVar-- == 8) ... -.. rubric:: "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 @@ -744,16 +756,18 @@ meaningless. Your game will be clearer and easier to debug if you instead create new property variables -- with appropriate names -- as part of your ``Object`` and ``Class`` definitions. -.. rubric:: Common properties and attributes +.. _common-props: -As an alternative to creating new individual properties which apply only -to a single object (or class of objects), it's possible to devise -properties and new attributes which, like those defined by the library, -are available on *all* objects. The need to do this is actually quite -rare, and is mostly confined to library extensions (for example, the -``pname.h`` extension which we encountered in "Captain Fate: take 3" on -page 147 gives every object a ``pname`` property and a -``phrase_matched`` attribute). To create them, you would use these +Common properties and attributes +-------------------------------- + +As an alternative to creating new individual properties which apply only to +a single object (or class of objects), it's possible to devise properties +and new attributes which, like those defined by the library, are available +on *all* objects. The need to do this is actually quite rare, and is mostly +confined to library extensions (for example, the ``pname.h`` extension +which we encountered in :doc:`12` gives every object a ``pname`` property +and a ``phrase_matched`` attribute). To create them, you would use these directives near the start of your source file: .. code-block:: inform @@ -770,7 +784,10 @@ properties (of which the library currently defines around forty-eight). On the other hand, the number of individual properties which you can add is virtually unlimited. -.. rubric:: Setting up the object tree +.. _setting-up-tree: + +Setting up the object tree +-------------------------- Throughout this guide, we've defined the initial position of each object within the overall object tree either by explicitly mentioning its @@ -896,14 +913,14 @@ The disadvantages include: We prefer to explicitly name the parent, but you'll encounter both forms very regularly. -.. rubric:: Quotes in "name" properties +Quotes in "name" properties +--------------------------- -We went to some lengths, way back in "Things in quotes" on page 55, to -explain the difference between double quotes ``"..."`` (strings to be -output) and single quotes ``'...'`` (input tokens -- dictionary words). -Perhaps somewhat unfortunately, Inform allows you to blur this clean -distinction: you can use double quotes in name properties and Verb -directives: +We went to some lengths, way back in :ref:`things-in-quotes`, to explain +the difference between double quotes ``"..."`` (strings to be output) and +single quotes ``'...'`` (input tokens -- dictionary words). Perhaps +somewhat unfortunately, Inform allows you to blur this clean distinction: +you can use double quotes in name properties and Verb directives: .. code-block:: inform @@ -920,7 +937,8 @@ directives: dictionary words, not strings; it's just as easy -- and far clearer -- to stick rigidly to the preferred punctuation. -.. rubric:: Obsolete usages +Obsolete usages +--------------- Finally, remember that Inform has been evolving since 1993. Over that time, Graham has taken considerable care to maintain as much diff --git a/chapters/15.rst b/chapters/15.rst index c8840de..ad7d85f 100644 --- a/chapters/15.rst +++ b/chapters/15.rst @@ -156,13 +156,12 @@ well), and make whatever seems a sensible correction. .. rubric:: Warnings -Warnings are not immediately catastrophic, but you should get rid of -them to ensure a good start at finding run-time mistakes (see "Debugging -your game" on page 197). You may declare a variable and then not use it; -you may mistake assignment and arithmetic operators (``=`` instead of -``==``); you may forget the comma that separates properties, etc. For -all these and many other warnings, Inform has found something which is -legal but doubtful. +Warnings are not immediately catastrophic, but you should get rid of them +to ensure a good start at finding run-time mistakes (see :doc:`16`). You +may declare a variable and then not use it; you may mistake assignment and +arithmetic operators (``=`` instead of ``==``); you may forget the comma +that separates properties, etc. For all these and many other warnings, +Inform has found something which is legal but doubtful. One common incident is to return in the middle of a statement block, before the rest of statements can be reached. This is not always as @@ -180,16 +179,14 @@ string has been printed, and the ``give match ~light`` line will never happen. Inform detects the fault and warns you. Probably the designer's intention was: - Compiling *à la carte* ====================== - One of the advantages of Inform is its portability between different systems and machines. Specific usage of the compiler varies accordingly, but some features should be in all environments. To obtain precise information about any particular version, run the compiler with the -``-h1`` switch -- see "Switches" on page 193. +``-h1`` switch -- see :ref:`switches`. Often the compiler is run with the name of your source file as its only parameter. This tells the compiler to "read this file using Strict mode and @@ -254,6 +251,7 @@ example: !============================================================================ +.. _switches: Switches ======== @@ -326,7 +324,7 @@ and ``-X``. Some of the more useful switches are: :samp:`-D -X` Include respectively the debugging verbs and the Infix debugger in the - story file (see "Debugging your game" on page 197). + story file (see :doc:`16`). :samp:`-h1 -h2` Display help information about the compiler. ``-h1`` produces diff --git a/conf.py b/conf.py index 49695f8..1621a52 100644 --- a/conf.py +++ b/conf.py @@ -288,7 +288,7 @@ latex_documents = [ #latex_use_parts = False # If true, show page references after internal links. -latex_show_pagerefs = False +latex_show_pagerefs = True # If true, show URL addresses after external links. #latex_show_urls = False -- 2.31.1