X-Git-Url: https://jxself.org/git/?p=ibg.git;a=blobdiff_plain;f=chapters%2F04.rst;h=8958b593acfd262bec6a10bac624ef842ae908ad;hp=9c48dc4c403f92bf96f709c1571f9455447bebf4;hb=f9eb50b5024de49b2df4b5daab471731840195d3;hpb=f68b82bdb2f596bfa811693302a8980ae46dff14 diff --git a/chapters/04.rst b/chapters/04.rst index 9c48dc4..8958b59 100644 --- a/chapters/04.rst +++ b/chapters/04.rst @@ -1,11 +1,9 @@ -.. raw:: latex - - \newpage - ====================== Reviewing the basics ====================== +.. highlight:: inform + .. epigraph:: | *G was a gamester, who had but ill-luck;* @@ -36,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:: @@ -55,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. @@ -66,20 +64,21 @@ 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; -to reset the value of the location variable to the ``before_cottage`` -object, and we wrote:: +to reset the value of the ``location`` variable to the +``before_cottage`` object, and we wrote:: if (nest in branch) deadflag = 2; 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 ================== @@ -90,7 +89,12 @@ room is an object, each item that the player sees and touches is an object; indeed the player herself is also an object (one that's automatically defined by the library). -The general model of an **object** definition looks like this:: +.. todo:: + + The set-off below needs to be tweaked or perhaps a custom lexer + created to get italics in the right places. + +The general model of an :term:`object` definition looks like this:: Object obj_id "external_name" parent_obj_id with property value , @@ -104,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 @@ -182,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, @@ -204,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:: @@ -234,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. @@ -288,52 +293,64 @@ This causes another change in the relationships. The bird is now a child of the player (and *not* of the forest), and the player is both a parent (of the bird) and a child (of the forest). -In this diagram, we show how the object relationships change during the -course of the game. The straight lines represent parent--child -relationships, with the parent object at the top of the line, and the child -object at the bottom. +Here we show how the object relationships change during the course of the +game. The straight lines represent parent--child relationships, with the +parent object at the top of the line, and the child object at the bottom. + +1. At the start of the game: + + .. blockdiag:: /figures/heidiobj1.diag + :align: center + :scale: 80% + +2. The player types: ``GO EAST`` + + .. blockdiag:: /figures/heidiobj2.diag + :align: center + :scale: 80% + +3. The player types: ``TAKE THE BIRD`` + + .. blockdiag:: /figures/heidiobj3.diag + :align: center + :scale: 80% + +4. The player types: ``GO NORTHEAST`` -.. list-table:: - :widths: 1 3 5 + .. blockdiag:: /figures/heidiobj4.diag + :align: center + :scale: 80% - * - 1. - - At the start of the game: - - .. image:: /images/heidiobj1.* +5. The player types: ``PUT BIRD IN NEST`` - * - 2. - - The player types: ``GO EAST`` - - .. image:: /images/heidiobj2.* + .. blockdiag:: /figures/heidiobj5.diag + :align: center + :scale: 80% - * - 3. - - The player types: ``TAKE THE BIRD`` - - .. image:: /images/heidiobj3.* +6. The player types: ``TAKE NEST`` - * - 4. - - The player types: ``GO NORTHEAST`` - - .. image:: /images/heidiobj4.* + .. blockdiag:: /figures/heidiobj6.diag + :align: center + :scale: 80% - * - 5. - - The player types: ``PUT BIRD IN NEST`` - - .. image:: /images/heidiobj5.* +7. The player types: ``UP`` - * - 6. - - The player types: ``TAKE NEST`` - - .. image:: /images/heidiobj6.* + .. blockdiag:: /figures/heidiobj7.diag + :align: center + :scale: 80% - * - 7. - - The player types: ``UP`` - - .. image:: /images/heidiobj7.* +8. The player types: ``PUT NEST ON BRANCH`` - * - 8. - - The player types: ``PUT NEST ON BRANCH`` - - .. image:: /images/heidiobj8.* + .. blockdiag:: /figures/heidiobj8.diag + :align: center + :scale: 80% 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 @@ -355,16 +372,17 @@ 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 not at a -line break are preserved, though). These two strings are equivalent:: +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 +*not* at a line break are preserved, though). These two strings are +equivalent:: "This is a string of characters." @@ -389,7 +407,7 @@ which could equally have been defined thus:: Constant Headline "^A simple Inform example^by Roger Firth and Sonja Kesserich.^"; -and as the value of an object description property:: +and as the value of an object ``description`` property:: description "Too young to fly, the nestling tweets helplessly.", @@ -397,8 +415,8 @@ 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 +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 @@ -428,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:: @@ -458,10 +476,10 @@ interpreter executes that statement: it performs an assignment:: deadflag = 2; -which changes the value of the library variable ``deadflag`` from its -current value to 2. Incidentally, if statements are often written on two -lines, with the "controlled" statement indented. This makes it easier to -read, but doesn't change the way that it works:: +which changes the value of the library variable ``deadflag`` from its +current value to 2. Incidentally, ``if`` statements are often written +on two lines, with the "controlled" statement indented. This makes it +easier to read, but doesn't change the way that it works:: if (nest in branch) deadflag = 2; @@ -475,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; ]; @@ -509,11 +527,12 @@ call. You may have noticed that, although we've defined a routine named ``Initialise``, we've never actually called it. Don't worry -- the - routine is called, by the Inform library, right at the start of a game. + routine *is* called, by the Inform library, right at the start of a + game. .. 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::