From 9e9feffd79cc1c4aa9c387afe98e16c7fbfae78d Mon Sep 17 00:00:00 2001 From: David Griffith Date: Thu, 14 Apr 2016 06:24:25 -0700 Subject: [PATCH] Some proofreading and fixes here and there. --- about.rst | 9 ++++ chapters/01.rst | 6 +-- chapters/02.rst | 28 +++++----- chapters/03.rst | 49 +++++++++--------- chapters/04.rst | 48 ++++++++--------- chapters/05.rst | 4 +- chapters/10.rst | 134 ++++++++++++++++++++++-------------------------- 7 files changed, 139 insertions(+), 139 deletions(-) diff --git a/about.rst b/about.rst index 295abe8..9c8f55e 100644 --- a/about.rst +++ b/about.rst @@ -100,6 +100,15 @@ placeholder: for example you should read the Inform statement: print "*string*"; +.. todo:: + + The above will not render correctly in PDF. In PDF the leading + quotes always appear with at least one backquote. At the moment, the + best solution I can think up is to have a script fire off after LaTeX + generation to take care of this problem so that when the LaTeX code + is compiled, we'll get the correct glyphs. At the moment, I don't + know how to make such a script automatically run. + as meaning "display on the player's screen the arbitrary character or characters which are represented here by the placeholder *string*". Examples might include:: diff --git a/chapters/01.rst b/chapters/01.rst index fcdb5be..119904c 100644 --- a/chapters/01.rst +++ b/chapters/01.rst @@ -145,8 +145,8 @@ Some of the more obvious differences are highlighted by these questions: Our example of narrative prose is written in the third person; it refers to the hero as "Wilhelm" and "he" and "him", watching and - reporting on his activities from afar. In this sample IF game, you are - the hero, seeing everything through Wilhelm's eyes. + reporting on his activities from afar. In this sample IF game, + *you* are the hero, seeing everything through Wilhelm's eyes. * What happens next? @@ -168,7 +168,7 @@ Some of the more obvious differences are highlighted by these questions: You can tell when you've come to the end of a regular narrative -- you read the last sentence, and you know there's no more. In IF, it's - clear enough when you reach an end; what's much less apparent is + clear enough when you reach *an* end; what's much less apparent is whether that's the only conclusion. In the transcript from the example game, you win by shooting the apple from Walter's head. But what if you miss? What if you hit him by mistake? Or fire instead at the diff --git a/chapters/02.rst b/chapters/02.rst index 9d727c0..32f06a1 100644 --- a/chapters/02.rst +++ b/chapters/02.rst @@ -119,8 +119,8 @@ write an Inform adventure game: 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 environment and - lots of useful standard definitions; + file in order to provide the **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 @@ -463,16 +463,18 @@ Follow these steps: Now, if you double-click the file, it should open in TextEdit so that you can see how it's written, though it probably won't mean much -- yet. - The above process may affect only this specific file. To change the - program that opens by default all ``.inf`` files, try this: + .. note:: - * right-click on the file (or Ctrl-click) + The above process may affect only this specific file. To change + the program that opens by default *all* ``.inf`` files, try this: - * select ``Get Info`` + * right-click on the file (or Ctrl-click) - * in the ``Open with`` tab, select TextEdit as the application + * select ``Get Info`` - * click the ``Change All...`` button, and confirm the change when asked. + * in the ``Open with`` tab, select TextEdit as the application + + * click the ``Change All...`` button, and confirm the change when asked. 4. ``MyGame1.command`` is a Terminal Shell Script (a UNIX executable command-line file, a kind of text-only computer program from the days @@ -596,11 +598,11 @@ 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 source file, as - we'll explain in the next chapter. + 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 + source file, as we'll explain in the next chapter. Once you've finished editing those lines, ``Save`` the file (not ``SaveAs``), overwriting the original, and make sure that your text editor diff --git a/chapters/03.rst b/chapters/03.rst index 72332e3..aff3993 100644 --- a/chapters/03.rst +++ b/chapters/03.rst @@ -88,12 +88,12 @@ that we design will start out like this. Follow these steps: Ensure the file is named ``Heidi.inf``, rather than ``Heidi.txt`` or ``Heidi.inf.txt``. - Remember that, throughout this guide, we place the "TYPE" symbol + Remember that, throughout this guide, we place the "``TYPE``" symbol alongside pieces of code that we recommend you to type into your own game files as you read through the examples (which, conversely, means - that you don't need to type the unmarked pieces of code). You'll learn - Inform more quickly by trying it for yourself, rather than just taking - our word for how things work. + that you *don't* need to type the unmarked pieces of code). You'll + learn Inform more quickly by trying it for yourself, rather than just + taking our word for how things work. .. todo:: @@ -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: + **string**) of characters to be displayed: .. code-block:: inform6 @@ -584,17 +584,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 **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:: @@ -743,14 +744,14 @@ at the top of the tree. Again, not many surprises in this definition: name 'wide' 'firm' 'flat' 'bough' 'branch', has static supporter; -The only new things are those two labels. ``static`` is similar to -``scenery``: it prevents the branch from being picked up by the player -character, but *doesn't* suppress mention of it when describing the -setting. And ``supporter`` is rather like the ``container`` that we used -for the nest, except that this time the player character can put other -objects *onto* the branch. (In passing, we'll mention that an object can't -normally be both a ``container`` and a ``supporter``.) And so here are our -objects again: +The only new things are those two labels. ``static`` is similar to +``scenery``: it prevents the branch from being picked up by the player +character, but *doesn't* suppress mention of it when describing the +setting. And ``supporter`` is rather like the ``container`` that we +used for the nest, except that this time the player character can put +other objects *onto* the branch. (In passing, we'll mention that an +object can't normally be both a ``container`` *and* a ``supporter``.) +And so here are our objects again: .. code-block:: inform6 diff --git a/chapters/04.rst b/chapters/04.rst index 249fdb1..8c6a7ed 100644 --- a/chapters/04.rst +++ b/chapters/04.rst @@ -67,8 +67,8 @@ 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; @@ -351,16 +351,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 **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." @@ -385,7 +386,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.", @@ -393,12 +394,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 **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 @@ -454,10 +455,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; @@ -505,7 +506,8 @@ 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 diff --git a/chapters/05.rst b/chapters/05.rst index 89b54da..ca11e0b 100644 --- a/chapters/05.rst +++ b/chapters/05.rst @@ -261,7 +261,7 @@ This time, however, we've done it using one statement rather than two. It turns out that the sequence "``print`` a string which ends with a newline character, and then ``return true``" is so frequently needed that there's a special statement which does it all. That is, this single statement (where -you'll note that the string doesn't need to end in ``^``):: +you'll note that the string *doesn't* need to end in ``^``):: print_ret "It's such a lovely day -- much too nice to go inside."; @@ -467,7 +467,7 @@ The extended ``if`` statement:: if (bird in nest && nest in branch) deadflag = 2; should now be read as: "Test whether the ``bird`` is currently in (or on) -the ``nest``, and whether the ``nest`` is currently on (or in) the +the ``nest``, *and* whether the ``nest`` is currently on (or in) the ``branch``; if both parts are ``true``, set the value of ``deadflag`` to 2; otherwise, do nothing". diff --git a/chapters/10.rst b/chapters/10.rst index f93ada8..d0c9638 100644 --- a/chapters/10.rst +++ b/chapters/10.rst @@ -288,7 +288,7 @@ the movement which is not allowed): Notice how the syntax coloring thinks that the exclaimation point above is a comment. This is another problem with the built-in inform6 - syntax colorer. + syntax highlighter. That takes care of entering the booth. But what about leaving it? Players may type EXIT or OUT while they are inside an enterable @@ -448,42 +448,36 @@ something else to describe it: ], has enterable proper; -.. todo:: - - Figure out how to set off this entire note section as an indented block +.. note:: -NOTE : although the text of our guide calls Benny's establishment a -"café" -- note the acute "e" -- the game itself simplifies this to -"cafe". We do this for clarity, not because Inform doesn't support -accented characters. The *Inform Designer's Manual* explains in detail -how to display these characters in "§1.11 *How text is printed*" and -provides the whole Z-machine character set in Table 2. In our case, we -could have displayed this:: + although the text of our guide calls Benny's establishment a "café" + -- note the acute "e" -- the game itself simplifies this to "cafe". + We do this for clarity, not because Inform doesn't support accented + characters. The *Inform Designer's Manual* explains in detail how to + display these characters in "§1.11 *How text is printed*" and + provides the whole Z-machine character set in Table 2. In our case, + we could have displayed this:: - The town's favourite for a quick snack, Benny's café has a 50's ROCKETSHIP look. + The town's favourite for a quick snack, Benny's café has a 50's ROCKETSHIP look. -by defining the ``description`` property as any of these: + by defining the ``description`` property as any of these: -.. code-block:: inform6 + .. code-block:: inform6 - description - "The town's favourite for a quick snack, Benny's caf@'e has a 50's - ROCKETSHIP look.", + description + "The town's favourite for a quick snack, Benny's caf@'e has a 50's + ROCKETSHIP look.", - description - "The town's favourite for a quick snack, Benny's caf@@170 has a 50's - ROCKETSHIP look.", + description + "The town's favourite for a quick snack, Benny's caf@@170 has a 50's + ROCKETSHIP look.", - description - "The town's favourite for a quick snack, Benny's caf@{E9} has a 50's - ROCKETSHIP look.", + description + "The town's favourite for a quick snack, Benny's caf@{E9} has a 50's + ROCKETSHIP look.", -However, all three forms are harder to read than the vanilla "cafe", so -we've opted for the simple life. - -.. todo:: - - Indented block ends here + However, all three forms are harder to read than the vanilla "cafe", so + we've opted for the simple life. Unlike the sidewalk object, we offer more than a mere description. Since the player may try ENTER CAFE as a reasonable way of access -- which @@ -613,44 +607,38 @@ with a test like this: .. todo:: That block of code above should be colored. Is there a defect in the - syntax coloring code? + syntax highlighting code? where 39 is the number for the standard message "That's not something you need to refer to in the course of this game" -- displayed when the player mentions a noun which is listed in a room's name property, as we did for the ``street``. -.. todo:: - - Begin big chunk of indented text. Also, NOTE should be in bigcaps. - -NOTE : remember that when we are testing for different values of the -same variable, we can also use the switch statement. For the Miscellany -entry, the following code would work just as nicely: - -.. code-block:: inform6 - - ... - Miscellany: - switch (lm_n) { - 19: - if (clothes has worn) - "In your secret identity's outfit, you manage most - efficaciously to look like a two-cent loser, a - good-for-nothing wimp."; - else - "Now that you are wearing your costume, you project - the image of power UNBOUND, of ballooned, - multicoloured MUSCLE, of DASHING yet MODEST chic."; - 38: - "That's not a verb you need to SUCCESSFULLY save the day."; - 39: - "That's not something you need to refer to in order to SAVE the day."; - } - -.. todo:: - - End big indented chunk +.. note:: + + remember that when we are testing for different values of the + same variable, we can also use the switch statement. For the + Miscellany entry, the following code would work just as nicely: + + .. code-block:: inform6 + + ... + Miscellany: + switch (lm_n) { + 19: + if (clothes has worn) + "In your secret identity's outfit, you manage most + efficaciously to look like a two-cent loser, a + good-for-nothing wimp."; + else + "Now that you are wearing your costume, you project + the image of power UNBOUND, of ballooned, + multicoloured MUSCLE, of DASHING yet MODEST chic."; + 38: + "That's not a verb you need to SUCCESSFULLY save the day."; + 39: + "That's not something you need to refer to in order to SAVE the day."; + } Not surprisingly, the default message for self-examination: "As good looking as ever" is a ``Miscellany`` entry -- it's number 19 -- so we @@ -671,21 +659,19 @@ experience grows. .. todo:: - Begin big indented chunk. That "whatever new look" needs to be italicized. + That "whatever new look" below needs to be italicized and bolded for LaTeX -NOTE: going back to our example, an alternative approach would be to set -the variable ``player.description`` in the ``Initialise`` routine (as we -did with "William Tell") to the "ordinary clothes" string, and then -later change it as the need arises. It is a variable, after all, and you -can alter its value with another statement like ``player.description = -*whatever new look*`` anywhere in your code. This alternative solution -might be better if we intended changing the description of the player -many times through the game. Since we plan to have only two states, the -``LibraryMessages`` approach will do just fine. - -.. todo:: +.. note:: - End big indented chunk + going back to our example, an alternative approach would be to set + the variable ``player.description`` in the ``Initialise`` routine (as we + did with "William Tell") to the "ordinary clothes" string, and then + later change it as the need arises. It is a variable, after all, and you + can alter its value with another statement like ``player.description =`` + *whatever new look* anywhere in your code. This alternative solution + might be better if we intended changing the description of the player + many times through the game. Since we plan to have only two states, the + ``LibraryMessages`` approach will do just fine. A final warning: as we explained when extending the standard verb grammars, you *could* edit the appropriate library file and change all -- 2.31.1