From: Glenn Hutchings Date: Fri, 22 Apr 2016 17:06:26 +0000 (+0100) Subject: Add glossary references in the correct places. X-Git-Url: https://jxself.org/git/?a=commitdiff_plain;h=f9eb50b5024de49b2df4b5daab471731840195d3;p=ibg.git Add glossary references in the correct places. --- diff --git a/chapters/02.rst b/chapters/02.rst index d8590cc..800190c 100644 --- a/chapters/02.rst +++ b/chapters/02.rst @@ -26,10 +26,10 @@ process slightly more complex. * For IF, you still have to write all of the text, but you also have to establish what text gets displayed when. Once you have written the - necessary Inform instructions, you use a **compiler** program to convert - them into a playable format. The resulting information is played by an - **interpreter** program, which permits you to interact with your - developing world. + necessary Inform instructions, you use a :term:`compiler` program to + convert them into a playable format. The resulting information is played + by an :term:`interpreter` program, which permits you to interact with + your developing world. With static fiction What You Write Is What You Read, but with IF the format in which you initially write the game doesn't bear much resemblance to the @@ -74,20 +74,21 @@ page 219, the player will see the following:: Clearly, there's more to writing IF than just laying down the words in the right order. Fortunately, we can make one immediate simplification: the translated form produced by the Inform compiler -- those cryptic numbers -and letters held in what's known as the **story file** -- is designed to be -read by the interpreter program. The story file is an example of a +and letters held in what's known as the :term:`story file` -- is designed +to be read by the interpreter program. The story file is an example of a "binary" file, containing data intended for use only by a computer program. Forget all that unreadable gibberish. So that leaves just the first form -- the one starting "``Constant Story``" --- which represents the tale written as a piece of IF. That's the **source -file** (so called because it contains the game in its original, source, -form) which you create on your computer. The source file is a "text" (or -"ASCII") file containing words and phrases which can be read -- admittedly -after a little tuition, which is what this guide is all about -- by humans. +-- which represents the tale written as a piece of IF. That's the +:term:`source file` (so called because it contains the game in its +original, source, form) which you create on your computer. The source file +is a "text" (or "ASCII") file containing words and phrases which can be +read -- admittedly after a little tuition, which is what this guide is all +about -- by humans. How do you create that source file? Using a third software program: an -**editor**. However, unlike the compiler and interpreter, this program +:term:`editor`. However, unlike the compiler and interpreter, this program isn't dedicated to the Inform system -- or even to IF. An editor is an entirely general tool for creating and modifying text files; you've probably already got a basic one on your computer (an IBM PC running @@ -103,7 +104,7 @@ Tell" story on page 219, 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 -not files which you have to create; they're standard **library files**, +not files which you have to create; they're standard :term:`library files`, part of the Inform system. All that you have to do is remember to Include them in every game that you write. Until you've a fair understanding of how Inform works, you've no need to worry about what they contain (though @@ -113,20 +114,21 @@ ones this guide will teach you to write). So, we've now introduced all of the bits and pieces which you need in order to write an Inform adventure game: -* a text **editor** program which can create and modify the **source file** - containing the descriptions and definitions of your game. Although it's - not recommended, you can even use a word-processing program to do this, - but you have to remember to save your game in Text File format; +* a text :term:`editor` program which can create and modify the + :term:`source file` containing the descriptions and definitions of your + game. Although it's not recommended, you can even use a word-processing + program to do this, but you have to remember to save your game in Text + File format; -* some Inform **library files** which you Include in your own game source - file in order to provide the **model world** -- a basic game +* some Inform :term:`library files` which you Include in your own game + source file in order to provide the :term:`model world` -- a basic game environment and lots of useful standard definitions; -* the Inform **compiler** program, which reads your source file (and the - library files) and translates your descriptions and definitions into - another format -- the **story file** -- intended only for... +* the Inform :term:`compiler` program, which reads your source file (and + the library files) and translates your descriptions and definitions into + another format -- the :term:`story file` -- intended only for... -* an Inform **interpreter** program, which is what players of your game +* an Inform :term:`interpreter` program, which is what players of your game use. A player doesn't require the source file, library files or compiler program, just the interpreter and the game in compiled format (which, because it's a binary file not meaningful to human eyes, neatly @@ -311,7 +313,7 @@ doing. There are four parts to the first line: .. note:: - On the command line, you sometimes also see a compiler **switch** + On the command line, you sometimes also see a compiler :term:`switch` such as ``-S``, used for controlling detailed aspects of how the compiler operates. Rather than do that here, we find it more convenient to place any necessary switches at the very top of the @@ -598,10 +600,10 @@ There are three parts to the second line: .. note:: - On the command line, you sometimes also see a compiler **switch** - such as ``-S``, used for controlling detailed aspects of how the - compiler operates. Rather than do that here, we find it more - convenient to place any necessary switches at the very top of the + On the command line, you sometimes also see a compiler :term:`switch` + such as ``-S``, used for controlling detailed aspects of how the + compiler operates. Rather than do that here, we find it more + convenient to place any necessary switches at the very top of the source file, as we'll explain in the next chapter. Once you've finished editing those lines, ``Save`` the file (not @@ -707,9 +709,9 @@ silly compilation errors. The Inform compiler is a powerful but undramatic software tool; it does an awful lot of work, but it does it all at once, without stopping to ask you any questions. Its input is a readable text source file; the output is a -story file, also sometimes known as a **Z-code file** (because it contains -the game translated into code for the Z-machine, which we describe in the -next section). +story file, also sometimes known as a :term:`Z-code file` (because it +contains the game translated into code for the Z-machine, which we describe +in the next section). If you're lucky, the compiler will translate your source file into Z-code; perhaps surprisingly, it doesn't display any form of "success" message when @@ -732,7 +734,7 @@ That's not just from one PC to another: exactly the same story file will run on a PC, a Mac, an Amiga, UNIX workstations, IBM mainframes, PalmOS hand-helds, and on dozens of other past, present and future computers. The magic that makes this happen is the interpreter program, a software tool -which pretends to be a simple computer called a **Z-machine**. The +which pretends to be a simple computer called a :term:`Z-machine`. The Z-machine is an imaginary (or "virtual") computer, but its design has been very carefully specified, so that an expert programmer can quite easily build one. And that's exactly what has happened: a Macintosh guru has diff --git a/chapters/03.rst b/chapters/03.rst index 517540f..8dd586a 100644 --- a/chapters/03.rst +++ b/chapters/03.rst @@ -167,9 +167,9 @@ looking at the source file. source. The instructions most commonly placed here are compiler switches, a way of controlling detailed aspects of how the compiler operates. These particular switches, two of many, are turning on - **Strict mode**, which makes the game less likely to misbehave when being - played, and **Debug mode**, which provides some extra commands which can - be helpful when tracking down problems. + :term:`Strict mode`, which makes the game less likely to misbehave when + being played, and :term:`Debug mode`, which provides some extra commands + which can be helpful when tracking down problems. .. note:: @@ -184,9 +184,9 @@ looking at the source file. line is ignored; if the ``!`` is halfway along a line, the compiler takes note of the first half, and then ignores the exclamation mark and everything after it on that line. We call material following an - exclamation mark, not seen by anybody else, a **comment**; it's often a - remark that we write to remind ourselves of how something works or why we - tackled a problem in a particular way. There's nothing special about + exclamation mark, not seen by anybody else, a :term:`comment`; it's often + a remark that we write to remind ourselves of how something works or why + we tackled a problem in a particular way. There's nothing special about those equals signs: they just produce clear lines across the page. It's always a good idea to comment code as you write it, for later it @@ -198,7 +198,7 @@ looking at the source file. By the way, the compiler *doesn't* give special treatment to exclamation marks in quoted text: ``!`` within quotes "..." is treated as a normal character. On this line, the first ``!`` is part of the sequence (or - **string**) of characters to be displayed: + :term:`string`) of characters to be displayed: .. code-block:: inform @@ -222,11 +222,12 @@ looking at the source file. you've typed, so it's worthwhile taking a bit of care to make it as readable as possible. -* Every game should have the **constant** definitions for ``Story`` (the - game's name) and ``Headline`` (typically, information on the game's - theme, copyright, authorship and so on). These two **string** values, - along with a release number and date, and details of the compiler, - compose the **banner** which is displayed at the start of each game. +* Every game should have the :term:`constant` definitions for ``Story`` + (the game's name) and ``Headline`` (typically, information on the game's + theme, copyright, authorship and so on). These two :term:`string` + values, along with a release number and date, and details of the + compiler, compose the :term:`banner` which is displayed at the start of + each game. * Every game needs the three lines which ``Include`` the standard library files -- that is, they merge those files' contents into your source file: @@ -248,9 +249,9 @@ looking at the source file. [ Initialise; ]; - The **routine** that we've defined here doesn't do anything useful, but - it still needs to be present. Later, we'll come back to ``Initialise`` - and explain what a routine is and why we need this one. + The :term:`routine` that we've defined here doesn't do anything useful, + but it still needs to be present. Later, we'll come back to + ``Initialise`` and explain what a routine is and why we need this one. * You'll notice that each of the items mentioned in the previous three rules ends with a semicolon. Inform is very fussy about its punctuation, @@ -283,8 +284,8 @@ involved: this sketch map shows the four that we'll use: .. image:: /images/heidi1.* :align: center -In IF, we talk about each of these locations as a **room**, even though in -this example none of them has four walls. So let's use Inform to define +In IF, we talk about each of these locations as a :term:`room`, even though +in this example none of them has four walls. So let's use Inform to define those rooms. Here's a first attempt: .. code-block:: inform @@ -351,11 +352,11 @@ Again, we can infer some general principles from these four examples: commonly, that light source is the room itself. A smidgeon of background may help set this into context (there's more in -the next chapter). An object can have both **properties** (introduced by -the keyword ``with``) and **attributes** (written after the word ``has``). -A property has both a name (like ``description``) and a value (like the -character string "``You stand outside a cottage. The forest stretches -east.``"); an attribute has merely a name. +the next chapter). An object can have both :term:`properties` (introduced +by the keyword ``with``) and :term:`attributes` (written after the word +``has``). A property has both a name (like ``description``) and a value +(like the character string "``You stand outside a cottage. The forest +stretches east.``"); an attribute has merely a name. In a little while, when you play this game, you'll observe that it starts like this: @@ -461,7 +462,7 @@ where the game starts, and we do this in the ``Initialise`` routine:: [ Initialise; location = before_cottage; ]; -``location`` is a **variable**, part of the library, which tells the +``location`` is a :term:`variable`, part of the library, which tells the interpreter in which room the player character currently is. Here, we're saying that, at the start of the game, the player character is in the ``before_cottage`` room. @@ -584,18 +585,18 @@ line to each definition: name 'bird^s' 'nest' 'twigs' 'moss', has ; -The ``name`` introduces a list in single quotes '...'. We call each of -those quoted things a **dictionary word**, and we do mean "word", not -"phrase" (``'baby'``\ ``'bird'`` rather than ``'baby bird'``); you can't -uses spaces, commas or periods *in* dictionary words, though there's a -space *between* each one, and the whole list ends with a comma. The -idea is that the interpreter decides which object a player is talking -about by matching what she types against the full set of all dictionary -words. If the player mentions BIRD, or BABY BIRD, or NESTLING, it's the -``baby bird`` that she means; if she mentions NEST, BIRD'S NEST or MOSS, -it's the ``bird's nest``. And if she types NEST BABY or BIRD TWIGS, the -interpreter will politely say that it doesn't understand what on earth -she's talking about. +The ``name`` introduces a list in single quotes '...'. We call each of +those quoted things a :term:`dictionary word`, and we do mean "word", not +"phrase" (``'baby'``\ ``'bird'`` rather than ``'baby bird'``); you can't +uses spaces, commas or periods *in* dictionary words, though there's a +space *between* each one, and the whole list ends with a comma. The idea +is that the interpreter decides which object a player is talking about by +matching what she types against the full set of all dictionary words. If +the player mentions BIRD, or BABY BIRD, or NESTLING, it's the ``baby bird`` +that she means; if she mentions NEST, BIRD'S NEST or MOSS, it's the +``bird's nest``. And if she types NEST BABY or BIRD TWIGS, the interpreter +will politely say that it doesn't understand what on earth she's talking +about. .. note:: diff --git a/chapters/04.rst b/chapters/04.rst index 1010f26..8958b59 100644 --- a/chapters/04.rst +++ b/chapters/04.rst @@ -34,10 +34,10 @@ beasts. .. rubric:: Constants -A **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 as a -stone tablet on which you carve a number: a carving can't be undone, so -that you see the same number every time you look at the stone. +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 +as a stone tablet on which you carve a number: a carving can't be undone, +so that you see the same number every time you look at the stone. So far, we've seen a ``Constant`` being set up with its value as a string of characters:: @@ -53,8 +53,8 @@ used in Inform. .. rubric:: Variables -A **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 +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 which you mark a number in chalk: whenever you need to, just wipe the board and write up a new number. @@ -64,8 +64,8 @@ which the library created like this:: Global location; Global deadflag; -The value of a **global variable** created in this way is initially 0, but -you can change it at any time. For example, we used the statement:: +The value of a :term:`global variable` created in this way is initially 0, +but you can change it at any time. For example, we used the statement:: location = before_cottage; @@ -76,8 +76,9 @@ 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 **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 "Routines" on +page 179) and about using object properties as variables (see "Objects" on +page 177). Object definitions ================== @@ -93,7 +94,7 @@ defined by the library). 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 **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 , @@ -107,8 +108,8 @@ The definition starts with the word ``Object`` and ends with a semicolon; in between are three major blocks of information: * immediately after the word ``Object`` is the header information; -* the word ``with`` introduces the object's **properties**; -* the word ``has`` introduces the object's **attributes**. +* the word ``with`` introduces the object's :term:`properties`; +* the word ``has`` introduces the object's :term:`attributes`. .. rubric:: Object headers @@ -185,8 +186,8 @@ with the ``description`` property in this particular example is a string of 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 **embedded -routine** (see "Embedded routines" on page 58). The only other type of +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:: capacity 10, @@ -207,11 +208,12 @@ As with properties, you can think of each attribute as a variable which is specifically associated with that object. However, an attribute is a much more limited form of variable, since it can have only two possible states: present, and absent (also known as set/clear, on/off, or true/false; -incidentally, a two-state variable like this is often called a **flag**). -Initially, an attribute is either present (if you mention its name in the -list) or absent (otherwise); if necessary, its state can change during play -(and this is relatively common). We often say that a certain object -currently *has* a certain attribute, or that conversely it *hasn't* got it. +incidentally, a two-state variable like this is often called a +:term:`flag`). Initially, an attribute is either present (if you mention +its name in the list) or absent (otherwise); if necessary, its state can +change during play (and this is relatively common). We often say that a +certain object currently *has* a certain attribute, or that conversely it +*hasn't* got it. The attributes that we've come across so far are:: @@ -237,9 +239,9 @@ recording exactly where each object is located, relative to the other objects in the game. Despite what we just said, Inform relationships *are* managed in terms of -**parent** and **child** objects, though in a much broader sense than -Wilhelm and Walter. When the player character is in a particular room -- -for example the forest -- we can say that: +:term:`parent` and :term:`child` objects, though in a much broader sense +than Wilhelm and Walter. When the player character is in a particular room +-- for example the forest -- we can say that: * the forest object is *the* parent of the player object, or alternatively * the player object is *a* child of the forest object. @@ -345,10 +347,10 @@ parent object at the top of the line, and the child object at the bottom. In this short example, we've taken a lot of time and space to spell out exactly how the objects relationship patterns -- generally known as the -**object tree** -- appear at each stage. Normally you wouldn't bother with -this much detail (a) because the interpreter does most of the work for you, -and (b) because in a real game there are usually too many objects for you -to keep track of. What's important is that you understand the basic +:term:`object tree` -- appear at each stage. Normally you wouldn't bother +with this much detail (a) because the interpreter does most of the work for +you, and (b) because in a real game there are usually too many objects for +you to keep track of. What's important is that you understand the basic principles: at any moment in time an object either has no parent (which probably means either that it's a room, or that it's floating in hyperspace and not currently part of the game) or exactly one parent -- the object @@ -370,12 +372,12 @@ Inform makes careful distinction between double and single quotes. .. rubric:: Double quotes -Double quotes ``"..."`` surround a **string** -- a letter, a word, a -paragraph, or almost any number of characters -- which you want the -interpreter to display while the game is being played. You can use the -tilde ``~`` to represent a double quote inside the string, and the -circumflex ``^`` to represent a newline (line break) character. -Upper-case and lower-case letters are treated as different. +Double quotes ``"..."`` surround a :term:`string` -- a letter, a word, a +paragraph, or almost any number of characters -- which you want the +interpreter to display while the game is being played. You can use the +tilde ``~`` to represent a double quote inside the string, and the +circumflex ``^`` to represent a newline (line break) character. Upper-case +and lower-case letters are treated as different. A long string can be split over several lines; Inform transforms each line break (and any spaces around it) into a single space (extra spaces @@ -413,12 +415,12 @@ Later, you'll find that they're also very common in ``print`` statements. .. rubric:: Single quotes -Single quotes ``'...'`` surround a **dictionary word**. This has to be -a single word -- no spaces -- and generally contains only letters (and -occasionally numbers and hyphens), though you can use ``^`` to represent -an apostrophe inside the word. Upper-case and lower-case letters are -treated as identical; also, the interpreter normally looks only at the -first nine characters of each word that the player types. +Single quotes ``'...'`` surround a :term:`dictionary word`. This has to be +a single word -- no spaces -- and generally contains only letters (and +occasionally numbers and hyphens), though you can use ``^`` to represent an +apostrophe inside the word. Upper-case and lower-case letters are treated +as identical; also, the interpreter normally looks only at the first nine +characters of each word that the player types. When the player types a command, the interpreter divides what was typed into individual words, which it then looks up in the dictionary. If it @@ -444,15 +446,15 @@ routine, and about two dozen types of statement (there's a complete list in .. rubric:: Statements -A **statement** is an instruction telling the interpreter to perform a +A :term:`statement` is an instruction telling the interpreter to perform a particular task -- to "do something" -- while the game is being played. A real game usually has lots and lots of statements, but so far we've encountered only a few. We saw:: location = before_cottage; -which is an example of an **assignment** statement, so-called because the -equals sign ``=`` assigns a new value (the internal ID of our +which is an example of an :term:`assignment` statement, so-called because +the equals sign ``=`` assigns a new value (the internal ID of our ``before_cottage`` room) to a variable (the global variable ``location`` which is part of the library). Later we saw:: @@ -491,9 +493,9 @@ and embedded routines. .. rubric:: Standalone routines -A **standalone routine** is a series of statements, collected together and -given a name. When the routine is "called" -- by its given name -- those -statements are executed. Here's the one that we've defined:: +A :term:`standalone routine` is a series of statements, collected together +and given a name. When the routine is "called" -- by its given name -- +those statements are executed. Here's the one that we've defined:: [ Initialise; location = before_cottage; ]; @@ -530,7 +532,7 @@ call. .. rubric:: Embedded routines -An **embedded routine** is much like a standalone routine, though it +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 we defined:: diff --git a/chapters/05.rst b/chapters/05.rst index f1342a9..1c0c623 100644 --- a/chapters/05.rst +++ b/chapters/05.rst @@ -300,9 +300,9 @@ This time, when we intercept the ``Climb`` action applied to the ``tree`` object, it's not in order to display a better message; it's because we want to move the player character to another room, just as if she'd typed UP. Relocating the player character is actually quite a complex business, but -fortunately all of that complexity is hidden: there's a standard **library -routine** to do the job, not one that we've written, but one that's -provided as part of the Inform system. +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 @@ -312,7 +312,7 @@ 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 **argument**. +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 @@ -529,7 +529,7 @@ parentheses, thus:: PlayerTo(clearing); -A value given in parentheses like that is called an **argument** of the +A value given in parentheses like that is called an :term:`argument` of the routine. In fact, a routine can have more than one argument; if so, they're separated by commas. For example, to move the player character to a room *without* displaying that room's description, we could have supplied diff --git a/chapters/06.rst b/chapters/06.rst index f706c86..902ff0b 100644 --- a/chapters/06.rst +++ b/chapters/06.rst @@ -267,14 +267,14 @@ We've done four things: #. We don't need to explicitly include the ``light`` attribute each time; every ``Room`` object has it automatically. -A **class** is a family of closely related objects, all of which behave in -the same way. Any properties defined for the class, and any attributes +A :term:`class` is a family of closely related objects, all of which behave +in the same way. Any properties defined for the class, and any attributes defined for the class, are automatically given to objects which you specify as belonging to that class; this process of acquisition just by being a -member of a class is called **inheritance**. In our example, we've defined -a ``Room`` class with a ``light`` attribute, and then we've specified four -objects each of which is a member of that class, and each of which gets -given a ``light`` attribute as a result of that membership. +member of a class is called :term:`inheritance`. In our example, we've +defined a ``Room`` class with a ``light`` attribute, and then we've +specified four objects each of which is a member of that class, and each of +which gets given a ``light`` attribute as a result of that membership. Why have we gone to this trouble? Three main reasons: @@ -408,7 +408,8 @@ The interesting things that this statement demonstrates are: nest", ``(a) nest`` would display "a bird's nest", ``(A) nest`` would display "A bird's nest" and ``(name) nest`` would display just "bird's nest". This use of a word in parentheses, telling the interpreter how to - display the following object's internal ID, is called a **print rule**. + display the following object's internal ID, is called a :term:`print + rule`. * There's a library variable ``self`` which always contains the internal ID of the current object, and is really convenient when using a ``Class``. diff --git a/chapters/07.rst b/chapters/07.rst index 4a8031b..8289c38 100644 --- a/chapters/07.rst +++ b/chapters/07.rst @@ -619,7 +619,7 @@ we *could* write two ``if`` statements:: enough. How's Frau Tell? Give her my best wishes.~^"; but that's unbearably clumsy; instead, we use the braces to group the -``move`` and ``print`` statement into a **statement block** (sometimes +``move`` and ``print`` statement into a :term:`statement block` (sometimes known as a code block) which counts as a single statement for the purposes of control by the ``if`` statement. :: diff --git a/chapters/08.rst b/chapters/08.rst index 656baa4..5ee56f8 100644 --- a/chapters/08.rst +++ b/chapters/08.rst @@ -564,8 +564,8 @@ the end of every turn; these are the values that it's expecting to find: * 2 -- the game is over. The interpreter displays "You have won". * any other value -- the game is over, but there aren't any appropriate messages built into the library. Instead, the interpreter looks for an - **entry point** routine called ``DeathMessage`` -- which we must provide - -- where we can define our own tailored "end messages". + :term:`entry point` routine called ``DeathMessage`` -- which we must + provide -- where we can define our own tailored "end messages". In this game, we never set ``deadflag`` to 1, but we do use values of 2 and 3. So we'd better define a ``DeathMessage`` routine to tell players diff --git a/chapters/09.rst b/chapters/09.rst index 67f7aa5..448a152 100644 --- a/chapters/09.rst +++ b/chapters/09.rst @@ -158,7 +158,7 @@ of the variable -- ``self`` or ``location`` -- which is being checked. A better approach might be to rework our ``BeenHereBefore`` routine so that it does both jobs, but we somehow need to tell it which variable's value is to be checked. That's easy: we design the routine so that it expects an -**argument**:: +:term:`argument`:: [ BeenToBefore this_room; if (this_room has visited) return true; @@ -180,7 +180,7 @@ routine doesn't care where the argument came from; it just sees a value which it knows as ``this_room``, and which it then uses to test for the ``visited`` attribute. On the second line we supply ``location`` as the argument, but the routine just sees another value in its ``this_room`` -variable. ``this_room`` is called a **local variable** of the +variable. ``this_room`` is called a :term:`local variable` of the ``BeenToBefore`` routine, one that must be set to a suitable value each time that the routine is called. In this example routine, the value needs to be a room object; we could also check an explicit named room:: diff --git a/chapters/11.rst b/chapters/11.rst index 49e2080..92ce631 100644 --- a/chapters/11.rst +++ b/chapters/11.rst @@ -93,11 +93,12 @@ let the action continue, ``true`` to prevent it. and others that are not. Should these ones that are not be promoted to having a typewriter font? -The Receive action is generated by the library in the PutOnSub action -handler, and also in InsertSub (so a command like PUT BIRD IN NEST sends -a Receive to the nest object). There’s a matching LetGo, generated by -the library from commands like TAKE KEY OFF COUNTER and REMOVE BIRD FROM -NEST. Receive and LetGo are examples of what’s called a **fake action**. +The Receive action is generated by the library in the PutOnSub action +handler, and also in InsertSub (so a command like PUT BIRD IN NEST sends a +Receive to the nest object). There’s a matching LetGo, generated by the +library from commands like TAKE KEY OFF COUNTER and REMOVE BIRD FROM +NEST. Receive and LetGo are examples of what’s called a :term:`fake +action`. .. note:: diff --git a/chapters/14.rst b/chapters/14.rst index 234f502..f943789 100644 --- a/chapters/14.rst +++ b/chapters/14.rst @@ -87,8 +87,8 @@ player), and we use the placeholders ``obj_id``, ``var_id``, Statements ========== -A **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 +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 @@ -212,10 +212,10 @@ In ``print`` and ``print_ret`` statements, each ``value`` can be: Directives ========== -A **directive** is an instruction intended for the compiler, telling it -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. +A :term:`directive` is an instruction intended for the compiler, telling it +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 diff --git a/chapters/15.rst b/chapters/15.rst index 238c68f..c8840de 100644 --- a/chapters/15.rst +++ b/chapters/15.rst @@ -191,14 +191,14 @@ 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. -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 from it generate a Version 5 story file of the same name". The -source file is mostly full of statements which define how the game is to -behave at run-time, but will also include compile-time instructions -directed at the compiler itself (although such an instruction looks a -lot like a **statement**, it's actually quite different in what it does, -and is known as a **directive**). We have already seen the ``Include`` +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 +from it generate a Version 5 story file of the same name". The source file +is mostly full of statements which define how the game is to behave at +run-time, but will also include compile-time instructions directed at the +compiler itself (although such an instruction looks a lot like a +:term:`statement`, it's actually quite different in what it does, and is +known as a :term:`directive`). We have already seen the ``Include`` directive: :samp:`Include "{filename}";` diff --git a/chapters/16.rst b/chapters/16.rst index dbbd704..6d358e0 100644 --- a/chapters/16.rst +++ b/chapters/16.rst @@ -56,12 +56,12 @@ 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.) -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. -We'll cover briefly a few of these actions, and tell you what they do. +To help you out in this daunting task, Inform has a stock of special +actions: the debugging verbs. They become available at run-time when the +source file is compiled in :term:`Debug mode` (``-D switch``). When you are +ready to release your game, you’ll have to recompile, switching off Debug +to avoid allowing the players to benefit from the debugging verbs. We'll +cover briefly a few of these actions, and tell you what they do. Command lists @@ -237,20 +237,18 @@ TIMERS (or TIMERS ON ) and TIMERS 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 ============