Fix for Jira bug I7-2380

inform7/Internal/Inter/Architecture16Kit/Sections/Mathematics.i6t

@@ -19,6 +19,15 @@ addresses, we need to compare them with the following routine, which returns
     return -1;
 ];
 
+@h Fully random word.
+This should be our best try at a single word consisting of 16 uniformly
+random bits. |random($100)-1| is a fully random byte.
+
+=
+[ FullyRandomWord;
+	return (random($100)-1)*$100 + (random($100)-1);
+];
+
 @h Integer roots.
 We are unable to provide VM support for taking square or cube roots rapidly:
 

inform7/Internal/Inter/Architecture32Kit/Sections/Mathematics.i6t

@@ -20,6 +20,15 @@ addresses, we need to compare them with the following routine, which returns
 	return 0;
 ];
 
+@h Fully random word.
+This should be our best try at a single word consisting of 32 uniformly random bits.
+
+=
+[ FullyRandomWord w;
+	@random 0 w;
+	return w;
+];
+
 @h Integer square root.
 Although this routine performs integer square root, it does so using Glulx's
 floating-point operations if available (with code contributed by Andrew

inform7/Internal/Inter/BasicInformKit/Sections/Utilities.i6t

@@ -226,12 +226,31 @@ a random number between 17 and 4 is the same thing as a random number
 between 4 and 17, and there is therefore no pair of $n$ and $m$ corresponding
 to an empty range of values.
 
+The following trick, devised by Zed Lopez in 2023, is designed to work even
+when the range width (here called $s$) is larger than the maximum signed
+integer size, so that the signed comparison $s > 0$ fails. In that case, it
+appears alarmingly to go into an infinite loop, but the loop terminates with
+a probability of at least 0.5 on each iteration. Even in the worst case of the
+range, the expected number of iterations is only 2, and the probability of taking
+more than 50 iterations is less than 0.0000000000000001, which is obviously
+negligible. But we check the iteration count anyway in case a rigged random
+number generator is being used, e.g. for story testing purposes, which happens
+to be biased in a really unlucky way for us.
+
 =
-[ GenerateRandomNumber n m s;
-	if (n==m) return n;
-	if (n>m) { s = n; n = m; m = s; }
-	n--;
-	return random(m-n) + n;
+[ GenerateRandomNumber n m s it;
+    if (n==m) return n;
+    if (n>m) { s = n; n = m; m = s; }
+    n--;
+    s = m - n;
+    if (s > 0) return random(s) + n;
+    n++;
+    do {
+		s = FullyRandomWord();
+		if ((s >= n) && (s <= m)) return s;
+		it++;
+    } until (it > 50);
+    return n;
 ];
 Constant R_DecimalNumber = GenerateRandomNumber;
 Constant R_PrintTimeOfDay = GenerateRandomNumber;

resources/Documentation/Examples/3AM.txt

@@ -31,7 +31,7 @@ For: Z-Machine
 	
 	The can of root beer is a closed openable container carried by the player. The can of root beer is either agitated or calm.
 
-Because the can of root beer should have some reactions to having been shaken later in the game, we need to borrow a few ideas from the chapter on Time:
+Because the can of root beer should have some reactions to having been shaken later in the game, we need to borrow a few ideas from the chapter on [Time]:
 
 	{**}Instead of shaking the can of root beer:
 		the can calms down in five turns from now;
@@ -55,3 +55,4 @@ Because the can of root beer should have some reactions to having been shaken la
 		say "The root beer is disappointingly flat. That's what you get for shaking it up!"
 	
 	Test me with "get box / shake box / open box / shake box / listen to can / shake can / listen to can / wait / wait / wait / wait / wait / listen to can / open can".
+

resources/Documentation/Examples/AARPGnosis.txt

@@ -67,3 +67,4 @@ Let's have the Encyclopedia describe itself differently depending on whether it'
 		say "complete ".
 	
 	Test me with "get aarhus-aaron / look / inventory / get aam-aardvark / look / get gnu-zygote / look / get aarp-gnosis / look / inventory / drop set / look / get set / get a-aalto / inventory".
+

resources/Documentation/Examples/ADayForFreshSushi.txt

@@ -5,7 +5,7 @@ Index: Person who comments on the player's every action
 Description: A complete story by Emily Short, called "A Day for Fresh Sushi", rewritten using Inform 7. Noteworthy is the snarky commenter who remarks on everything the player does, but only the first time each action is performed.
 For: Z-Machine
 
-The following is an almost-completely-faithful rewrite of Emily Short's "A Day for Fresh Sushi", which was originally written using the (very different) Inform 6 programming language. The -- let us be honest and call it a gimmick -- of this game is the evil fish, who has some unpleasant remark to offer on pretty much every action. But the effect would wear off fast if he repeated himself, so these comments need to be single-use only.
+The following is an almost-completely-faithful rewrite of Emily Short's "A Day for Fresh Sushi", which was originally written using the (very different) Inform 6 programming language. The – let us be honest and call it a gimmick – of this game is the evil fish, who has some unpleasant remark to offer on pretty much every action. But the effect would wear off fast if he repeated himself, so these comments need to be single-use only.
 
 Inform 7's repeated action syntax makes it much tidier to write the same scenario, so:
 
@@ -138,7 +138,6 @@ Inform 7's repeated action syntax makes it much tidier to write the same scenari
 	
 	The description of the telegram is "A telegram, apparently. And dated three days ago. [fixed letter spacing]TRIUMPH OURS STOP BACK SOON STOP BE SURE TO FEED FISH STOP[variable letter spacing]". [For printing options see 4.13.] Understand "yellow paper" as the telegram.
 	
-
 	After examining the telegram for the first time:
 		say "'So,' blubs the evil fish. 'How about it? Little food over here?'"
 	
@@ -198,8 +197,7 @@ Inform 7's repeated action syntax makes it much tidier to write the same scenari
 	The description of the bouquet is "Okay, so it's silly and sentimental and no doubt a waste of money, of which there is never really enough, but: you miss her. You've missed her since ten seconds after she stepped aboard the shuttle to Luna Prime, and when you saw these -- her favorites, pure golden tulips like springtime -- you had to have them." Understand "flowers" or "tulip" or "tulips" as the bouquet.
 	
 	After examining the bouquet for the first time:
-		say "'Oh, you shouldn't have,' says the fish. 'For me??'
-		You just respond with a livid glare."
+		say "'Oh, you shouldn't have,' says the fish. 'For me??'	You just respond with a livid glare."
 	
 		Instead of smelling the bouquet for the first time:
 			say "'Mmm-mm,' says the fish. 'Damn, I sure wish I had olfactory abilities. Hey, if I did, I might be even better at noticing the presence or absence of FOOD.'"
@@ -239,3 +237,4 @@ Inform 7's repeated action syntax makes it much tidier to write the same scenari
 	The maximum score is 1.
 	
 	Test me with "x fish / g / kiss fish / x aquarium / x gravel / x seaweed / i / x telegram / x bouquet / smell bouquet / x lingerie / g / x hat / x window / open window / x painting / g / x cabinet / open cabinet / x cloths / search cloths / open food / feed fish".
+

resources/Documentation/Examples/AE.txt

@@ -22,3 +22,4 @@ Rules about going to regions make it easy to exclude the player from a large por
 		end the story finally.
 	
 	Test me with "e / n / e / get pass / e".
+

resources/Documentation/Examples/AHaughtySpirit.txt

@@ -46,7 +46,7 @@ Now we just have to create windows and some action rules for interacting with th
 	Instead of examining a window:
 		say "[The noun] [if the noun is open]opens over[otherwise]gives a view of[end if] [the list of rooms overlooked by the noun]."
 
-Here we must anticipate a little from the chapter on Relations, and provide ourselves with a way of keeping track of how windows and rooms relate to one another:
+Here we must anticipate a little from the chapter on [Relations], and provide ourselves with a way of keeping track of how windows and rooms relate to one another:
 
 	{**}Overlooking relates various windows to various rooms. The verb to overlook means the overlooking relation. The initial appearance of a window is usually "[The item described] overlooks [the list of rooms overlooked by the item described]."
 	
@@ -57,3 +57,4 @@ Here we must anticipate a little from the chapter on Relations, and provide ours
 	Test me with "jump through window / open window / jump through window / d / x narrow window / open window / climb through window / e / up / down".
 
 We could then add rules to allow the player to look through windows and see things in the rooms below, but that would require more material from later chapters.
+

resources/Documentation/Examples/AHumbleWaysideFlower.txt

@@ -47,3 +47,4 @@ For brevity, we will ignore the existence of mothers. It is a sad world.
 	Test me with "out / west / east / west".
 
 Monsieur St Just never appears on the scene in this piece, but if we did put him somewhere the player could find him, he, too, would be properly introduced.
+

resources/Documentation/Examples/APointForNeverSavingTheGame.txt

@@ -2,7 +2,7 @@ Example: *** A point for never saving the game
 Location: Out of world actions
 RecipeLocation: Saving and Undoing
 Index: A point for never saving the game
-Description: In some of the late 1970s "cave crawl" adventure games, an elaborate scoring system might still leave the player perplexed as to why an apparently perfect play-through resulted in a score which was still one point short of the supposed maximum. Why only 349 out of 350? The answer varied, but sometimes the last point was earned by never saving the game - in other words by playing it right through with nothing to guard against mistakes (except perhaps UNDO for the last command), and in one long session.
+Description: In some of the late 1970s "cave crawl" adventure games, an elaborate scoring system might still leave the player perplexed as to why an apparently perfect play-through resulted in a score which was still one point short of the supposed maximum. Why only 349 out of 350? The answer varied, but sometimes the last point was earned by never saving the game - in other words by playing it right through with nothing to guard against mistakes (except perhaps ``undo`` for the last command), and in one long session.
 For: Untestable
 
 Here is one way to score this point with Inform:
@@ -17,3 +17,4 @@ That has the right effect, but it just isn't sneaky enough. Instead let us quiet
 Sneakier, certainly, but now we could get the bonus even if the game ends earlier on, so finally:
 
 	When play ends: if the number of saves is 0 and the score is 349, increment the score.
+

resources/Documentation/Examples/AViewOfGreenHills.txt

@@ -2,10 +2,10 @@ Example: *** A View of Green Hills
 Location: Adjacent rooms and routes through the map
 RecipeLocation: Continuous Spaces and The Outdoors
 Index: LOOK [direction] command
-Description: A LOOK [direction] command which allows the player to see descriptions of the nearby landscape.
+Description: A ``look`` [direction] command which allows the player to see descriptions of the nearby landscape.
 For: Z-Machine
 
-Suppose a game in which the player is wandering an open landscape with long vistas, allowing them to LOOK in some direction, or even look at an adjacent location.
+Suppose a game in which the player is wandering an open landscape with long vistas, allowing them to ``look`` in some direction, or even look at an adjacent location.
 
 	{*}"A View of Green Hills"
 	
@@ -20,9 +20,9 @@ Suppose a game in which the player is wandering an open landscape with long vist
 		if the viewed item is not a room, say "You can't see anything promising that way." instead;
 		try looking toward the viewed item.
 
-In rules about action handling, "noun" refers to the first object that the player has mentioned in their command, so if the player typed >LOOK WEST, "let the viewed item be the room noun from the location" would be processed as "let the viewed item be the room west from the location", and so on.
+In rules about action handling, "noun" refers to the first object that the player has mentioned in their command, so if the player typed ``look west``, "let the viewed item be the room noun from the location" would be processed as "let the viewed item be the room west from the location", and so on.
 
-We can at need override the default behavior, if it is not going to be appropriate for the player to see the next room over. There is only sky above at any time, so...
+We can at need override the default behaviour, if it is not going to be appropriate for the player to see the next room over. There is only sky above at any time, so...
 
 	{**}Instead of facing up:
 		say "Above you is bright sky."
@@ -40,3 +40,4 @@ This design allows us to create descriptions for rooms (as seen from the outside
 		say "Even from here you can make out the silhouette of the Acropolis."
 	
 	Test me with "look north / look south / look up / look east / east / look west".
+

resources/Documentation/Examples/AboutInformsRegularExpressionSupport.txt

@@ -5,36 +5,37 @@ Index: About Inform's regular expression support
 Description: Some footnotes on Inform's regular expressions, and how they compare to those of other programming languages.
 For: Untestable
 
-There is not really any unanimity about what regular expression language is. The unix tools sed and grep extend on Kleene's original grammar. Henry Spencer's regex library extended on this again, and was a foundation for Perl, but Perl once again went further. Philip Hazel's PCRE, despite the name Perl Compatible Regular Expressions, makes further extensions still, and so on.
+There is not really any unanimity about what regular expression language is. The unix tools sed and grep extend on Kleene's original grammar. Henry Spencer's regex library extended on this again, and was a foundation for Perl, but Perl once again went further. Philip Hazel's ``pcre``, despite the name Perl Compatible Regular Expressions, makes further extensions still, and so on.
 
-Inform's regular expressions are modelled on those of Perl, as the best de facto standard we have, but a few omissions have been inevitable. Inform's regex matcher must occupy source code less than one hundredth the size of PCRE, and it has very little memory. Inform aims to behave exactly like Perl except as follows:
+Inform's regular expressions are modelled on those of Perl, as the best de facto standard we have, but a few omissions have been inevitable. Inform's regex matcher must occupy source code less than one hundredth the size of ``pcre``, and it has very little memory. Inform aims to behave exactly like Perl except as follows:
 
-	(i) Inform allows angle brackets as synonymous with square brackets, for reasons explained above. This means literal angle brackets have to be escaped as "\<" and "\>" in Inform regular expressions, which is unnecessary in Perl.
+1. Inform allows angle brackets as synonymous with square brackets, for reasons explained above. This means literal angle brackets have to be escaped as "\<" and "\>" in Inform regular expressions, which is unnecessary in Perl.
 
-	(ii) Inform only has single-line mode, not multiline mode: this removes need for the mode-switches "(?m)" and "(?s)" and the positional markers "\A" and "\Z". Multiline mode is idiosyncratic to Perl and is a messy compromise to do with holding long files of text as single strings, yet treating them as lists of lines at the same time: this would not be sensible for Inform. Similarly, because there is no ambiguity about how line breaks are represented in Inform strings (by a single "\n"), initial newline convention markers such as "(*ANYCRLF)" are unsupported.
+2. Inform only has single-line mode, not multiline mode: this removes need for the mode-switches "(?m)" and "(?s)" and the positional markers "\A" and "\Z". Multiline mode is idiosyncratic to Perl and is a messy compromise to do with holding long files of text as single strings, yet treating them as lists of lines at the same time: this would not be sensible for Inform. Similarly, because there is no ambiguity about how line breaks are represented in Inform strings (by a single "\n"), initial newline convention markers such as "(*ANYCRLF)" are unsupported.
 
-	(iii) The codes "\a", "\r", "\f", "\e", "\0" for alarm, carriage return, form feed, escape and the zero character are unsupported: none of these can occur in an Inform string.
+3. The codes "\a", "\r", "\f", "\e", "\0" for alarm, carriage return, form feed, escape and the zero character are unsupported: none of these can occur in an Inform string.
 
-	(iv) Inform does not allow characters to be referred to by character code (whereas Perl allows "\036" for an octal character code, "\x7e" for a hexadecimal one, "\cD" for a control character). This is because we do not want the user to know whether text is internally stored as ZSCII or Unicode.
+4. Inform does not allow characters to be referred to by character code (whereas Perl allows "\036" for an octal character code, "\x7e" for a hexadecimal one, "\cD" for a control character). This is because we do not want the user to know whether text is internally stored as ZSCII or Unicode.
 
-	(v) Inform's character class "\p" (and its negation "\P") have no equivalent in Perl, and Inform's understanding of "\w" is different. Perl defines this as an upper or lower case English letter, underscore or digit, which is good for programming-language identifiers, but bad for natural language - for instance, "é" is not matched by "\w" in Perl, but unquestionably it appears in words. Inform therefore defines "\w" as the negation of "\s" union "\p".
+5. Inform's character class "\p" (and its negation "\P") have no equivalent in Perl, and Inform's understanding of "\w" is different. Perl defines this as an upper or lower case English letter, underscore or digit, which is good for programming-language identifiers, but bad for natural language - for instance, "é" is not matched by "\w" in Perl, but unquestionably it appears in words. Inform therefore defines "\w" as the negation of "\s" union "\p".
 
-	(vi) Inform supports only single-digit grouping numbers "\1" to "\9", whereas Perl allows "\10", "\11", ...
+6. Inform supports only single-digit grouping numbers "\1" to "\9", whereas Perl allows "\10", "\11", ...
 
-	(vii) POSIX named character ranges are not supported. These are only abbreviations in any case, and are not very useful. (Note that the POSIX range "[:punct:]", which is supposedly for punctuation, includes many things we do not want to think of that way - percentage signs, for instance - and so "\p" has a more natural-language-based definition.)
+7. POSIX named character ranges are not supported. These are only abbreviations in any case, and are not very useful. (Note that the POSIX range "[:punct:]", which is supposedly for punctuation, includes many things we do not want to think of that way - percentage signs, for instance - and so "\p" has a more natural-language-based definition.)
 
-	(viii) Character classes can be used inside ranges, so that "<\da-f>" is legal, but not as ends of contiguous runs, so that "<\d-X>" is not legal. (As reckless as this is, it is legal in Perl.)
+8. Character classes can be used inside ranges, so that "<\da-f>" is legal, but not as ends of contiguous runs, so that "<\d-X>" is not legal. (As reckless as this is, it is legal in Perl.)
 
-	(ix) For obvious reasons, escapes to Perl code using the notation "(?{...})" are unsupported, and so is the Perl iteration operator "\G".
+9. For obvious reasons, escapes to Perl code using the notation "(?{...})" are unsupported, and so is the Perl iteration operator "\G".
 
-	(x) Perl's extended mode "(?x)", a lexical arrangement which allows expressions to be expanded out as little computer programs with comments, is unsupported. It would look awful syntax-coloured in the Inform interface and is not a style of coding to be encouraged.
+10. Perl's extended mode "(?x)", a lexical arrangement which allows expressions to be expanded out as little computer programs with comments, is unsupported. It would look awful syntax-coloured in the Inform interface and is not a style of coding to be encouraged.
 
 Inform further does not support the Python extension of named subexpression groups, nor the Java extension of the possessive quantifier "++". There was only so much functionality we could squeeze in.
 
-As verification of Inform's matching algorithm, we took the Perl 5 source code's notorious "re-test.txt" set of 961 test cases, removed the 316 using features unsupported by Inform (220 tested multiline mode, for instance), and ran the remaining 645 cases through Inform. It agrees with Perl on 643 of these: the two outstanding are -
+As verification of Inform's matching algorithm, we took the Perl 5 source code's notorious "re-test.txt" set of 961 test cases, removed the 316 using features unsupported by Inform (220 tested multiline mode, for instance), and ran the remaining 645 cases through Inform. It agrees with Perl on 643 of these: the two outstanding are –
 
-	(i) Perl is able to match "^(a\1?){4}$" against "aaaaaa" but Inform is not - Inform's backtracking is not as good when it comes to repetitions of groupings which are recursively defined. (Note that the optional "\1" match refers to the value of the bracketed expression which contains it, so that the interpretation is different on each repetition. Here to match we have to interpret "?" as 0, 0, 1, 0 repeats respectively as we work through the "{4}".)
+1. Perl is able to match "^(a\1?){4}$" against "aaaaaa" but Inform is not - Inform's backtracking is not as good when it comes to repetitions of groupings which are recursively defined. (Note that the optional "\1" match refers to the value of the bracketed expression which contains it, so that the interpretation is different on each repetition. Here to match we have to interpret "?" as 0, 0, 1, 0 repeats respectively as we work through the "{4}".)
 
-	(ii) Perl matches "((&lt;a-c>)b*?\2)*" against "ababbbcbc" finding the match "ababb", whereas Inform finds the match "ababbbcbc". This is really a difference of opinion about whether the outer asterisk, which is greedy, should be allowed three matches rather than two if to do so requires the inner asterisk, which is not greedy, to eat more than it needs on one of those three matches.
+2. Perl matches "((<a-c>)b*?\2)*" against "ababbbcbc" finding the match "ababb", whereas Inform finds the match "ababbbcbc". This is really a difference of opinion about whether the outer asterisk, which is greedy, should be allowed three matches rather than two if to do so requires the inner asterisk, which is not greedy, to eat more than it needs on one of those three matches.
+
+Case 1 is a sacrifice to enable Inform's back-tracking to use less memory. Case 2 simply seems unimportant.
 
-Case (i) is a sacrifice to enable Inform's back-tracking to use less memory. Case (ii) simply seems unimportant.

resources/Documentation/Examples/AboutTheExamples.txt

@@ -5,21 +5,25 @@ Index: About the examples
 Description: An explanation of the examples in this documentation, and the asterisks attached to them. Click the heading of the example, or the example number, to reveal the text.
 For: Untestable
 
+[ZL: .png to be substituted]::
+
 This is the first of about 400 numbered examples. In a few cases, such as this one, they provide a little background information, but almost all demonstrate Inform source text. The techniques demonstrated tend to be included either because they are frequently asked for, or because they show how to achieve some interesting effect.
 
-The same examples are included in <b>both</b> of the books of documentation, but in a different order: in <i>Writing with Inform</i>, they appear near the techniques used to make them work; in <i>The Inform Recipe Book</i>, they are grouped by the effects they provide. For instance, an example called "Do Pass Go", about the throwing of a pair of dice, appears in the "Randomness" section of <i>Writing with Inform</i> and also in the "Dice and Playing Cards" section of <i>The Inform Recipe Book</i>. Clicking the italicised WI and RB buttons at the right-hand side of an example's heading switches between its position in each book.
+The same examples are included in **both** of the books of documentation, but in a different order: in *Writing with Inform*, they appear near the techniques used to make them work; in *The Inform Recipe Book*, they are grouped by the effects they provide. For instance, an example called [Do Pass Go], about the throwing of a pair of dice, appears in the [Randomness] section of *Writing with Inform* and also in the [Dice and Playing Cards] section of *The Inform Recipe Book*. Clicking the italicised WI and RB buttons at the right-hand side of an example's heading switches between its position in each book.
 
 Many computing books quote excerpts from programs, but readers have grown wary of them: they are tiresome to type in, and may only be fragments, or may not ever have been tested. The authors of Inform have tried to avoid this. All but two dozen examples contain entire source texts. A single click on the paste icon ///paste.png/// (always placed just left of the double-quoted title) will write the complete source text into the Source panel. All that is then required is to click the Go button, and the example should translate into a working game.
 
-In most cases, typing the single command TEST ME will play through a few moves to show off the effect being demonstrated. (You may find it convenient to create a "scratch" project file for temporary trials like this, clearing all its text and starting again with each new test.)
+In most cases, typing the single command ``test me`` will play through a few moves to show off the effect being demonstrated. (You may find it convenient to create a "scratch" project file for temporary trials like this, clearing all its text and starting again with each new test.)
 
 As part of the testing process which verifies a new build of Inform, each example in turn is extracted from this documentation, translated, played through, and the resulting transcript mechanically checked. So the examples may even work as claimed. But the flesh is weak, and there are bound to be glitches. We would welcome reports, so that future editions can be corrected.
 
 Each example is loosely graded by difficulty: if they were exercises in a textbook, the asterisks would indicate how many marks each question scores. As a general rule:
 
-	///asterisk.png/// - A simple example, fairly easily guessed.
-	///asterisk.png/// ///asterisk.png/// - A complicated or surprising example.
-	///asterisk.png/// ///asterisk.png/// ///asterisk.png/// - An example needing detailed knowledge of many aspects of the system.
-	///asterisk.png/// ///asterisk.png/// ///asterisk.png/// ///asterisk.png/// - A complete scenario, containing material not necessarily relevant to the topic being demonstrated.
+[ZL: better without bullets; first line actually appears mangled; possibly a bug in IFM parsing ...]::
 
-In general, the main text of <i>Writing with Inform</i> tries never to assume knowledge of material which has not yet appeared, but the trickier examples almost always need to break this rule.
+- * A simple example, fairly easily guessed.
+- ** A complicated or surprising example.
+- *** An example needing detailed knowledge of many aspects of the system.
+- **** A complete scenario, containing material not necessarily relevant to the topic being demonstrated.
+
+In general, the main text of *Writing with Inform* tries never to assume knowledge of material which has not yet appeared, but the trickier examples almost always need to break this rule.

resources/Documentation/Examples/AccessAllAreas.txt

@@ -5,7 +5,7 @@ Index: The Pointy Hat of Liminal Transgression
 Description: The Pointy Hat of Liminal Transgression allows its wearer to walk clean through closed doors.
 For: Z-Machine
 
-If somebody tries to walk through a closed door, the "can't go through closed doors rule" usually stops them. This is a rule belonging to the "check going" rulebook. These names are fairly explanatory when written out, but hard to remember: fortunately we don't need to remember them, as the Index panel contains a full inventory of the check, carry out and report rules for every action, showing all of their names and the order in which they are checked. (We can also find out which rules are stopping an action by typing the testing command ACTIONS.)
+If somebody tries to walk through a closed door, the "can't go through closed doors rule" usually stops them. This is a rule belonging to the "check going" rulebook. These names are fairly explanatory when written out, but hard to remember: fortunately we don't need to remember them, as the Index panel contains a full inventory of the check, carry out and report rules for every action, showing all of their names and the order in which they are checked. (We can also find out which rules are stopping an action by typing the testing command ``actions``.)
 
 Here we make the rule do nothing provided a condition holds:
 
@@ -20,3 +20,4 @@ Here we make the rule do nothing provided a condition holds:
 	Test me with "n / wear hat / n".
 
 (The Pointy Hat may be useful in debugging a game, even if it never makes it into the final published work.)
+

resources/Documentation/Examples/Actaeon.txt

@@ -1,8 +1,8 @@
 Example: ** Actaeon
 Location: Understanding any, understanding rooms
-RecipeLocation: Traveling Characters
+RecipeLocation: Travelling Characters
 Index: FOLLOW command
-Description: A FOLLOW command allowing the player to pursue a person who has just left the room.
+Description: A ``follow`` command allowing the player to pursue a person who has just left the room.
 For: Z-Machine
 
 Suppose we want the player to be able to go after characters who are moving around the map. The trick, of course, is that once characters are gone they are no longer visible to "follow [person]", so we need "follow [any person]" to find them.
@@ -47,3 +47,4 @@ We do also have to make sure that whenever we move a person from room to room, w
 		if Artemis is visible, say "Artemis arrives from [the current location]."
 	
 	Test me with "wait / follow artemis / follow artemis / follow artemis".
+

resources/Documentation/Examples/ActorsStudio.txt

@@ -69,3 +69,4 @@ Here we construct a video camera to track and play back actions:
 	Test me with "set camera to recording / x lucas / lucas, take inventory / lucas, eat croissant / set camera to playing back / z".
 
 Notice that both Lucas' implied taking action (picking up the croissant) and his eating action are recorded on the same move.
+

resources/Documentation/Examples/Aftershock.txt

@@ -2,10 +2,10 @@ Example: *** Aftershock
 Location: New activities
 RecipeLocation: Televisions and Radios
 Index: Radios and other devices active when switched on
-Description: Modifying the rules for examining a device so that all devices have some specific behavior when switched on, which is described at various times.
+Description: Modifying the rules for examining a device so that all devices have some specific behaviour when switched on, which is described at various times.
 For: Z-Machine
 
-The built-in behavior of Inform is to print a line after a device is examined, saying whether the item is on or off. This is often inappropriate, and we could simply turn off that behavior in general by instructing Inform to ignore the "examine devices rule" (see the chapter on rulebooks).
+The built-in behaviour of Inform is to print a line after a device is examined, saying whether the item is on or off. This is often inappropriate, and we could simply turn off that behaviour in general by instructing Inform to ignore the "examine devices rule" (see the chapter on [Rulebooks]).
 
 Perhaps, though, we would like continue to have a short passage about the action of any switched on device; we'd just like a little more control over what it says from time to time. And in that case, we might change the rule to give a new activity control over that portion of the description:
 
@@ -28,7 +28,7 @@ Borrowing from the rulebooks chapter, we can replace the standard "examine devic
 			carry out the showing action activity with the noun;
 			now examine text printed is true.
 
-Thus far we have essentially replicated the original behavior, but we've made it possible to write specialized behavior for devices, and to invoke that behavior in other places:
+Thus far we have essentially replicated the original behaviour, but we've made it possible to write specialised behaviour for devices, and to invoke that behaviour in other places:
 
 	{**}Report switching on something:
 		say "You flip a switch. ";
@@ -60,7 +60,7 @@ This might be useful for an electric lamp kind:
 	
 	The flashlight is an electric lamp carried by the player. The description is "A shiny red flashlight." The portable radio is a device carried by the player. The description is "A small battery-operated radio which you received for free with your subscription to US News & World Report. It has served you well through many earthquakes past."
 
-And with our activity, we can override the flashlight's electric lamp behavior with new behavior:
+And with our activity, we can override the flashlight's electric lamp behaviour with new behaviour:
 
 	{**}Rule for showing action of the flashlight:
 		if the flashlight is switched on, say "A strong, narrow beam of light shines from the flashlight.";
@@ -76,3 +76,4 @@ And with our activity, we can override the flashlight's electric lamp behavior w
 		carry out the showing action activity with the radio instead.
 	
 	Test me with "examine light / switch light off / switch flashlight on / switch radio on / examine radio / examine flashlight".
+

resources/Documentation/Examples/AgeOfSteam.txt

@@ -26,3 +26,4 @@ The following source is very short and simple, yet it already feels surprisingly
 	Instead of entering the Flying Scotsman, say "Alas, the [time when Train Stop began] arrival is only to take on water, not to set down or pick up."
 	
 	Test me with "z / z / z / enter flying scotsman / z / z".
+

resources/Documentation/Examples/Ahem.txt

@@ -37,3 +37,4 @@ In general, we probably don't need to make our phrase definitions quite so flexi
 	Chateau Marmont is a room. Tom, Jack, Zsa-Zsa, and Wilma-Faye are people in the Chateau. Zsa-Zsa and Wilma-Faye are women.
 	
 	Test me with "wait / smell / listen".
+

resources/Documentation/Examples/AirConditioningIsStandard.txt

@@ -2,7 +2,7 @@ Example: **** Air Conditioning is Standard
 Location: Writing a paragraph about
 RecipeLocation: Event Scheduling
 Index: Paragraphs of flexible descriptions
-Description: Uses "writing a paragraph about" to make person and object descriptions that vary considerably depending on what else is going on in the room, including some randomized NPC interactions with objects or with each other.
+Description: Uses "writing a paragraph about" to make person and object descriptions that vary considerably depending on what else is going on in the room, including some randomised NPC interactions with objects or with each other.
 For: Z-Machine
 
 	{*}"Air Conditioning is Standard"
@@ -152,3 +152,4 @@ For: Z-Machine
 		say "sober grey gown ([sober grey gown condition])"
 	
 	Test me with "z / look / look / z / look / west / east / z  / look / z / look / z / look / west / east".
+

resources/Documentation/Examples/Alias-G.txt

@@ -13,7 +13,7 @@ Seven-digit telephone numbers are too long for Inform to handle when compiling t
 	
 	A phone number is a kind of value. 999-9999 specifies a phone number.
 
-Now we borrow some techniques from the Understanding chapter to set up dialing actions:
+Now we borrow some techniques from the [Understanding] chapter to set up dialing actions:
 
 	{**}Understand "dial [phone number] on [telephone]" as dialing it on. Understand "dial [phone number] on [something]" as dialing it on.
 	
@@ -36,7 +36,7 @@ We'll set up a little political espionage scenario from which our player can mak
 	
 	The player is wearing a housekeeping uniform and a brunette wig. The player carries a telephone called a Nokia.
 
-Borrowing again from the chapter on Understanding, we might arrange things so that the player knows and can call a few standard numbers with such syntax as CALL HOME:
+Borrowing again from the chapter on [Understanding], we might arrange things so that the player knows and can call a few standard numbers with such syntax as ``call home``:
 
 	{**}Understand "home" as 555-9200.
 
@@ -46,7 +46,7 @@ And what if we'd like to have the player learn some phone numbers during the gam
 	
 	Understand "Stephen" as 555-2513 when the blue paper is examined.
 
-This will understand CALL STEPHEN once the paper is examined; before that, the player will just get the "That's not a number you know" response that Inform uses for all attempts to call unknown names.
+This will understand ``call stephen`` once the paper is examined; before that, the player will just get the "That's not a number you know" response that Inform uses for all attempts to call unknown names.
 
 We'd better plant this paper for the player to find:
 
@@ -55,3 +55,4 @@ We'd better plant this paper for the player to find:
 	The drawer is part of the dresser. It is closed and openable. The dresser is in The Senator's Junior Suite. The lamp is on the dresser. The description of the dresser is "The single drawer is [if the drawer is open]open[otherwise]shut[end if]."
 	
 	Test me with "dial 555-9999 / call home on the telephone / phone the president / call stephen / open drawer / read paper / call stephen / put phone in drawer / close drawer / call stephen".
+

resources/Documentation/Examples/AlienInvasionPart23-G--I.txt

@@ -2,9 +2,11 @@
 
 
 
+(The current puzzle difficulty is set to easy.)
+
 Alien Invasion Part 23
 An Interactive Fiction
-Release 1 / Serial number 160428 / Inform 7 v10.1.0 / D
+Release 1 / Serial number 160428 / Inform 7 v10.2.0 / D
 
 Sewer Junction
 

resources/Documentation/Examples/AlienInvasionPart23-G.txt

@@ -4,7 +4,6 @@ RecipeLocation: Start-Up Features
 Index: Preferences file loaded on replaying
 Description: Keeping a preference file that could be loaded by any game in a series.
 For: Glulx
-ExternalFiles: prefs.glkdata
 
 Suppose that we have a series of games each of which allows the player to select a puzzle difficulty level. When the player plays a new game in the series, we want them to start out by default with the same difficulty level they faced earlier on, so we store this information in a small preferences file, as follows:
 
@@ -24,8 +23,8 @@ Suppose that we have a series of games each of which allows the player to select
 	When play begins:
 		if File of Preferences exists:
 			read File of Preferences into the Table of Preference Settings;
-			choose row 1 in the Table of Preference Settings;
-			say "(The current puzzle difficulty is set to [challenge level entry].)"
+		choose row 1 in the Table of Preference Settings;
+		say "(The current puzzle difficulty is set to [challenge level entry].)";
 	
 	Check quitting the game:
 		write File of Preferences from the Table of Preference Settings.
@@ -36,6 +35,7 @@ Suppose that we have a series of games each of which allows the player to select
 	
 	The Sewer Junction is a room.
 
-Our preference file is restricted to a single option here for simplicity's sake, but we could keep track of more information -- whether the player preferred verbose or brief room descriptions, screen configurations, and so on.
+Our preference file is restricted to a single option here for simplicity's sake, but we could keep track of more information – whether the player preferred verbose or brief room descriptions, screen configurations, and so on.
 
 If we were disposed to be somewhat crueler, we could use a similar method to make the player finish each episode of the series in order to "unlock" the next. All we would need to do is store a numerical password in our preferences file when the player finished a given level; the next level would check, say, the Table of Completed Levels for that password, and refuse to play unless the right number were present.
+

resources/Documentation/Examples/AllRoadsLeadToMars.txt

@@ -5,7 +5,7 @@ Index: Rooms player is forced to visit in order
 Description: Layout where the player is allowed to wander any direction he likes, and the map will arrange itself in order so that he finds the correct "next" location.
 For: Z-Machine
 
-Suppose we want to allow the player to wander freely in any direction, but ourselves maintain control over the order in which they encounter the rooms. This sort of effect emphasizes the order of the story-telling over any kind of rigorous simulation of space; on multiple play-throughs, the player might not find all the same rooms in the same locations.
+Suppose we want to allow the player to wander freely in any direction, but ourselves maintain control over the order in which they encounter the rooms. This sort of effect emphasises the order of the story-telling over any kind of rigorous simulation of space; on multiple play-throughs, the player might not find all the same rooms in the same locations.
 
 	{*}"All Roads Lead to Mars"
 	
@@ -25,3 +25,4 @@ Suppose we want to allow the player to wander freely in any direction, but ourse
 	Test me with "n / s / e / e".
 
 If we wanted still to be able to find routes between places, we could define a relationship of connection between rooms, which we would add to as we went along.
+

resources/Documentation/Examples/AlpacaFarm.txt

@@ -1,8 +1,8 @@
 Example: * Alpaca Farm
 Location: New commands for old grammar
 RecipeLocation: Clarification and Correction
-Index: USE action which divines rational behavior for a wide range of possible nouns
-Description: A generic USE action which behaves sensibly with a range of different objects.
+Index: USE action which divines rational behaviour for a wide range of possible nouns
+Description: A generic ``use`` action which behaves sensibly with a range of different objects.
 For: Z-Machine
 
 This example takes the ordering of grammar lines to its logical extreme, sorting the player's input into different categories depending on the kind and condition of the objects mentioned.
@@ -50,4 +50,5 @@ This example takes the ordering of grammar lines to its logical extreme, sorting
 	
 	Test me with "use gate / use blower / use nippers / use brush / use apple / remove sombrero / use sombrero".
 
-Whether we actually want a USE action is a subject of some theoretical debate in the IF community. On the one hand, it helps avoid guess-the-verb problems where the player cannot figure out what term to use in order to express a fairly simple idea. On the other, it encourages the player to think that all items have one and exactly one use, rather than getting them to consider the range of possibilities that arise from having a complex vocabulary.
+Whether we actually want a ``use`` action is a subject of some theoretical debate in the IF community. On the one hand, it helps avoid guess-the-verb problems where the player cannot figure out what term to use in order to express a fairly simple idea. On the other, it encourages the player to think that all items have one and exactly one use, rather than getting them to consider the range of possibilities that arise from having a complex vocabulary.
+

resources/Documentation/Examples/Alpha.txt

@@ -22,3 +22,4 @@ Sometimes we want to let testers of a game insert their own comments during a tr
 			reject the player's command.
 	
 	Test me with "x me / x troll / !this game is a bit dull so far / kiss troll / ? does this troll do anything? / :yawn".
+

resources/Documentation/Examples/Anchorite.txt

@@ -2,10 +2,10 @@ Example: * Anchorite
 Location: New commands for old grammar
 RecipeLocation: Entering and Exiting, Sitting and Standing
 Index: GET DOWN and DOWN understood as EXIT
-Description: By default, Inform understands GET OFF, GET UP, or GET OUT when the player is sitting or standing on an enterable object. We might also want to add GET DOWN and DOWN as exit commands, though.
+Description: By default, Inform understands ``get off``, ``get up``, or ``get out`` when the player is sitting or standing on an enterable object. We might also want to add ``get down`` and ``down`` as exit commands, though.
 For: Z-Machine
 
-With GET DOWN, we can replace the whole command, which will not interfere with the normal function of the TAKE verb, or allow the player to attempt to GET any other directions:
+With ``get down``, we can replace the whole command, which will not interfere with the normal function of the ``take`` verb, or allow the player to attempt to ``get`` any other directions:
 
 	{*}"Anchorite"
 	
@@ -13,9 +13,10 @@ With GET DOWN, we can replace the whole command, which will not interfere with t
 	
 	Understand "get down" as exiting.
 
-This doesn't cover the case where the player just types "DOWN", and we don't want to preempt the normal operation of the GO action here. So instead of writing a new understand instruction, we might catch this one at the action-processing level:
+This doesn't cover the case where the player just types ``down``, and we don't want to preempt the normal operation of the ``go`` action here. So instead of writing a new understand instruction, we might catch this one at the action-processing level:
 
 	{**}Instead of going down when the player is on a supporter:
 		try exiting.
 	
 	Test me with "down / enter pillar / get down / down / get down".
+

resources/Documentation/Examples/AnnoyotronJr.txt

@@ -20,3 +20,4 @@ For: Z-Machine
 		end the story.
 	
 	Test me with "z / z / look / g / g / g / no / z / z / z / no / z / out".
+

resources/Documentation/Examples/AntSensitiveSunglasses.txt

@@ -5,7 +5,7 @@ Index: Varying room description text
 Description: What are activities good for? Controlling output when we want the same action to be able to produce very flexible text depending on the state of the world -- in this case, making highly variable room description and object description text.
 For: Z-Machine
 
-Suppose we want to create an object -- or maybe even a series of objects -- that warp the player's perception of every room description and object around them.
+Suppose we want to create an object – or maybe even a series of objects – that warp the player's perception of every room description and object around them.
 
 We've already seen some ways to create variations in text. For instance, we could make a room description with if substitutions in it, like so:
 
@@ -41,9 +41,9 @@ Inform's usual rule-ranking also means that more-specific rules will override le
 		Rule for printing the room-description of the Kitchen when the player wears the sunglasses:
 		say "Are ants coming out of the sink? No, probably not."
 
-and have that rule override the behavior of the activity just in the kitchen. Meanwhile, our base room descriptions remain straightforward and uncluttered by if-statements.
+and have that rule override the behaviour of the activity just in the kitchen. Meanwhile, our base room descriptions remain straightforward and uncluttered by if-statements.
 
-Several other examples will show how to hook activities into existing actions: Crusoe goes into detail about how how to make the descriptions of things more variable, and Aftershock demonstrates activities for describing the behavior of switchable devices.
+Several other examples will show how to hook activities into existing actions: [Crusoe] goes into detail about how how to make the descriptions of things more variable, and [Aftershock] demonstrates activities for describing the behaviour of switchable devices.
 
 Here, we preview all of those methods, just to get a sense of how they work and why they might be useful in controlling a game. Subsequent chapters go into more detail about the syntax of creating activities and the list of activities that are already defined by Inform.
 
@@ -54,7 +54,9 @@ Here, we preview all of those methods, just to get a sense of how they work and
 To add a new activity to an existing Inform rule, we need to do three things:
 
 1) Define our new activity.
+
 2) Give a basic rule that says what is supposed to happen when that activity occurs, as in "Rule for..."
+
 3) Replace the existing rule in Inform's rulebooks with a new one that calls on our activity.
 
 Here we do this with examining:
@@ -169,3 +171,4 @@ But all of those details are re-copied from the standard rules, and the importan
 			end the story saying "You have lost your mind."
 	
 	Test me with "look / turn on microwave / turn off microwave / x apple / x sunglasses / s / wear sunglasses / look / x apple / n / turn on microwave".
+

resources/Documentation/Examples/Anteaters.txt

@@ -36,3 +36,4 @@ For: Z-Machine
 		now the idea of the gizmo is waiting.
 	
 	Test me with "get guide / look up spines in guide / x gizmo / get gizmo / i / x gizmo / drop gizmo / get gizmo / look up anteater colonies in guide / x gizmo / drop gizmo".
+

resources/Documentation/Examples/Apples.txt

@@ -7,7 +7,7 @@ For: Z-Machine
 
 Inform by default detects whether two objects can be disambiguated by any vocabulary available to the player. If so, it asks a question; if not, it picks one of the identical objects at random.
 
-Generally this produces good behavior. Occasionally, though, two objects have some distinguishing characteristic that doesn't appear in the object name. For instance, suppose we've created a class of apples that can be told apart depending on whether they've been bitten or not:
+Generally this produces good behaviour. Occasionally, though, two objects have some distinguishing characteristic that doesn't appear in the object name. For instance, suppose we've created a class of apples that can be told apart depending on whether they've been bitten or not:
 
 	An apple is a kind of thing. Consumption is a kind of value. The consumptions are pristine and bitten. An apple has a consumption. The description of an apple is "It is [consumption]."
 	
@@ -15,15 +15,21 @@ Generally this produces good behavior. Occasionally, though, two objects have so
 
 The player can meaningfully type
 
-	>EAT BITTEN APPLE
+``` transcript
+>eat bitten apple
+```
 
 or
 
-	>EAT PRISTINE APPLE
+``` transcript
+>eat pristine apple
+```
 
 but if they type
 
-	>EAT APPLE
+``` transcript
+>eat apple
+```
 
 Inform will, annoyingly, ask
 
@@ -51,7 +57,7 @@ This gives the player no indication of why Inform is making a distinction. So he
 		say "You consume the apple entirely.";
 		now the fruit is nowhere.
 
-Inform will also separate the bitten from the pristine apples in inventory listings and room descriptions, even though it's not clear why; we can improve on that behavior thus:
+Inform will also separate the bitten from the pristine apples in inventory listings and room descriptions, even though it's not clear why; we can improve on that behaviour thus:
 
 	{**}Before listing contents: group apples together.
 	
@@ -65,3 +71,4 @@ Inform will also separate the bitten from the pristine apples in inventory listi
 		if every apple held by the source is pristine, say "pristine ".
 	
 	Test me with "i / eat apple / i / eat apple / pristine / i / eat apple / pristine / i".
+

resources/Documentation/Examples/Aspect.txt

@@ -18,3 +18,4 @@ Named properties are not the only kind that Inform is able to understand referri
 	The widescreen TV is a television in the Office. The fifties TV is a television in the Office. The widescreen TV is 16:9. The fifties TV is 4:3.
 	
 	Test me with "examine european standard tv / x 16:9 tv / x 4:3 tv".
+

resources/Documentation/Examples/BadHairDay.txt

@@ -1,8 +1,8 @@
 Example: * Bad Hair Day
 Location: Instead rules
-RecipeLocation: Characterization
+RecipeLocation: Characterisation
 Index: Examining the player
-Description: Change the player's appearance in response to EXAMINE ME.
+Description: Change the player's appearance in response to ``examine me``.
 For: Z-Machine
 
 	{*}"Bad Hair Day"
@@ -13,3 +13,4 @@ For: Z-Machine
 		say "Oh, stop fussing. You look fine."
 	
 	Test me with "examine me".
+

resources/Documentation/Examples/Baedeker.txt

@@ -29,4 +29,4 @@ If our map is largely or entirely set inside a single building, we might want to
 
 Now we have a map made of white lines and boxes over a white background, which is not very exciting. If, however, we put a layer of black under this and slightly adjust the room shapes (using an image editor such as Adobe Illustrator), we can produce something that plausibly resembles a floorplan or museum map, like so:
 
-///Sophia.jpg///
+  ![Sophia](doc_images/Sophia.jpg)

resources/Documentation/Examples/Ballpark.txt

@@ -15,7 +15,7 @@ Sometimes it is more sensible to describe numbers roughly than in exact terms. F
 				say "[approximation entry]";
 				rule succeeds.
 
-Phrases will be explained more thoroughly in a later chapter, but as we have already seen in the examples, we can make a "To say..." phrase that will allow us to create our own text substitutions. In this case, we are going to replace the specific number with a vaguer one chosen from a chart, so:
+[Phrases] will be explained more thoroughly in a later chapter, but as we have already seen in the examples, we can make a "To say..." phrase that will allow us to create our own text substitutions. In this case, we are going to replace the specific number with a vaguer one chosen from a chart, so:
 
 	{**}Table of Numerical Approximation
 	threshold	approximation
@@ -36,3 +36,4 @@ The idea here is that we will work our way through the table until we hit a line
 	The population of the Stadium is 500. The population of the Hot Dog Stand is 3. The population of the Restroom is 750.
 	
 	Test me with "w / e / s".
+

resources/Documentation/Examples/BaritoneBass.txt

@@ -5,6 +5,8 @@ Index: Allowing the player to describe the main character before starting play
 Description: Letting the player pick a gender (or perhaps other characteristics) before starting play.
 For: Z-Machine
 
+[ZL: This example should either be cut or should accept "neither" ]::
+
 The "reading a command" activity is rather advanced; for the moment, what we need to understand is that we're intervening in commands at the start of play and insisting that the player's first instruction to the game consist of a choice of gender. After that point, the gender will be set and play will proceed as normal.
 
 In order to do the parsing, we define gender as a kind of value, and give several alternate names to each gender.
@@ -52,3 +54,4 @@ and use a "construction stage" variable to keep track of the current stage of ch
 
 	After reading a command when the current construction stage is choosing a vocal range:
 		...
+

resources/Documentation/Examples/BarterBarter.txt

@@ -5,7 +5,7 @@ Index: GIVE action for other characters
 Description: Allowing characters other than the player to give objects to one another, accounting for the possibility that some items may not be desired by the intended recipients.
 For: Z-Machine
 
-By default, if we make no modifications, telling one player to give something to another will fail, even if persuasion succeeds. This is because the default behavior of the GIVE command is interrupted by the "block giving rule" -- since in many cases we do not want people to exchange objects freely.
+By default, if we make no modifications, telling one player to give something to another will fail, even if persuasion succeeds. This is because the default behaviour of the ``give`` command is interrupted by the "block giving rule" – since in many cases we do not want people to exchange objects freely.
 
 However, suppose that we do want characters to be able to exchange articles freely: we allow persuasion to succeed and turn off the "block giving rule".
 
@@ -42,3 +42,4 @@ And now we might want to implement a way to keep track of whether the recipient
 Since we've defined this as a relation, we could change what the characters like and dislike during the course of the game, freely; for instance, characters might grow hungry and suddenly like all the edible articles.
 
 	{**}Test me with "x lewis / x clark / clark, give the slippers to lewis / clark, give the bread to lewis".
+

resources/Documentation/Examples/BattleOfRidgefield.txt

@@ -5,7 +5,7 @@ Index: Death message replaced
 Description: Completely replacing the endgame text and stopping the game without giving the player a chance to restart or restore.
 For: Z-Machine
 
-Occasionally, a piece of IF is sufficiently serious that it feels bathetic to offer the player the usual restore-restart-undo-quit options at the end. The following would replace "*** You have died ***" with a centered epitaph, then quit the game when the player hits a key.
+Occasionally, a piece of IF is sufficiently serious that it feels bathetic to offer the player the usual restore-restart-undo-quit options at the end. The following would replace "\*\*\* You have died \*\*\*" with a centered epitaph, then quit the game when the player hits a key.
 
 This example relies on a standard extension to avoid any fancy programming:
 
@@ -29,3 +29,4 @@ This example relies on a standard extension to avoid any fancy programming:
 		wait for any key;
 		stop game abruptly;
 		rule succeeds.
+

resources/Documentation/Examples/BayLeavesAndHoneyWine.txt

@@ -28,4 +28,4 @@ This produces a line-and-dot map, where the names of rooms do not appear inside
 
 We can then superimpose this on a vector map of Greece and tweak the exact positions of cities a little by hand (in Adobe Illustrator, as it happens, but other programs would also allow this level of editing). The result:
 
-///Greece.jpg///
+  ![Greece](doc_images/Greece.jpg)

resources/Documentation/Examples/Beachfront.txt

@@ -7,7 +7,7 @@ For: Z-Machine
 
 Suppose we have our player, a detective, searching for evidence; we don't want them to be able to use this evidence until they have performed the action that reveals it, but after that it should be visible in the room when they look.
 
-A simple way to do this is to start the object -- an envelope, in this scenario -- out of play, and only move it into the location when the player looks for it:
+A simple way to do this is to start the object – an envelope, in this scenario – out of play, and only move it into the location when the player looks for it:
 
 	{*}"Beachfront"
 	
@@ -32,3 +32,4 @@ Here we've changed the property of the envelope to keep track of the fact that i
 Notice that we have two rules that apply to "searching the desk", but one of them has a more specific set of parameters ("when the envelope is lost"). This means that Inform will consult that rule first and use it if it applies; it will only carry out our plain vanilla "instead of searching the desk" rule when the more restricted rule is not relevant.
 
 	{**}Test me with "x envelope / x desk / search desk / look / get envelope / x envelope".
+

resources/Documentation/Examples/BeeChambers.txt

@@ -1,8 +1,8 @@
 Example: * Bee Chambers
 Location: Now...
 RecipeLocation: Map
-Index: Maze with randomized room links
-Description: A maze with directions between rooms randomized at the start of play.
+Index: Maze with randomised room links
+Description: A maze with directions between rooms randomised at the start of play.
 For: Z-Machine
 
 Mazes are a traditional element of interactive fiction, often consisting of apparently identical rooms with exits that do not work reciprocally and which cause confusion.
@@ -32,3 +32,4 @@ The methods of mapping mazes are now fairly well understood and mazes themselves
 			now a random Bee Chamber is mapped outside place.
 	
 	Test me with "in / out / up / down / n / ne / nw / e / w / sw / se / s".
+

resources/Documentation/Examples/BeekeepersApprentice.txt

@@ -2,7 +2,7 @@ Example: ** Beekeeper's Apprentice
 Location: Line breaks and paragraph breaks
 RecipeLocation: Examining
 Index: Examining everything at once
-Description: Making the SEARCH command examine all the scenery in the current location.
+Description: Making the ``search`` command examine all the scenery in the current location.
 For: Z-Machine
 
 We have to create a suitable action and say what it does, and to repeat what we do through all the scenery items. That needs material from subsequent chapters, but is quite ordinary Inform all the same:
@@ -26,11 +26,14 @@ We have to create a suitable action and say what it does, and to repeat what we
 	
 	Test me with "search".
 
-The reason for this example is to show the use of saying "[run paragraph on]". It means we have output such as:
+The reason for this example is to show the use of saying `"[run paragraph on]"`. It means we have output such as:
 
-	>search
-	hive: The honeycombed hive is all around you, thrumming with life.
+``` transcript
+>search
+hive: The honeycombed hive is all around you, thrumming with life.
 
-	honey: Wax-sealed honey has been cached in many of the hexagonal nurseries.
+honey: Wax-sealed honey has been cached in many of the hexagonal nurseries.
+```
 
 Without the running on, the prompts "hive:" and "honey:" would be separated from the descriptions following them, which would look a little odd.
+

resources/Documentation/Examples/BeingPeter.txt

@@ -45,3 +45,4 @@ Now, as we saw, the 'no outcome' result will never be returned and printed as Ma
 	Test me with "ask maggie about love / ask maggie about income / take off hat / ask maggie about income".
 
 There are plenty of contexts where we might want named outcomes for clarity but not want to print the results literally afterward.
+

resources/Documentation/Examples/BeingPrepared.txt

@@ -32,3 +32,4 @@ Notice that, since Inform has created a pocket for the hoodie, we can now refer
 	Test me with "x hoodie / get hoodie / get knife / get map / i / put hoodie in pocket / put whistle in pocket / put map in pocket / put knife in pocket / i".
 
 Notice that Inform automatically refuses to put the hoodie into its own pocket: as a default, a container cannot contain something of which it is itself a part.
+

resources/Documentation/Examples/Belfry.txt

@@ -12,3 +12,4 @@ For: Z-Machine
 	In the Belfry is a man called the vicar. The indefinite article of the vicar is "your local".
 	
 	Test me with "look".
+

resources/Documentation/Examples/BeneathTheSurface.txt

@@ -37,3 +37,4 @@ The standard world model provides for the idea of containers and supporters, but
 	A treasure map underlies the easy chair. A skeleton is beneath the sofa. A blueprint of Atlantis, a lexicon of Linear A, and the key to Jimmy Hoffa's Mausoleum are under the rug.
 	
 	Test me with "look under the sofa / look under the rug / look under the easy chair / hide lexicon under rug".
+

resources/Documentation/Examples/BeverageService.txt

@@ -5,7 +5,7 @@ Index: DRINKing a potion which then goes away
 Description: A potion that the player can drink.
 For: Z-Machine
 
-Some kinds of game objects -- food, for instance -- can only sensibly be used once, and should then be destroyed. The EAT command already implements this, but suppose we also had a category of drinkable potions:
+Some kinds of game objects – food, for instance – can only sensibly be used once, and should then be destroyed. The ``eat`` command already implements this, but suppose we also had a category of drinkable potions:
 
 	{*}"Beverage Service"
 	
@@ -18,3 +18,4 @@ Some kinds of game objects -- food, for instance -- can only sensibly be used on
 		say "You quaff [the drink]. It goes down beautifully."
 	
 	Test me with "drink sparkly / i".
+

resources/Documentation/Examples/Bibliophilia.txt

@@ -5,7 +5,7 @@ Index: Bookshelf with numerous books
 Description: A bookshelf with a number of books, where the player's command to examine something will be interpreted as an attempt to look up titles if the bookshelf is present, but otherwise given the usual response.
 For: Z-Machine
 
-Suppose we want a bookshelf with a very large number of books on it. They aren't to be taken or carried around in the game, but they should be mentioned, and the player should be allowed to look them up by name. Furthermore, the player's attempts to examine something unrecognized should be understood as an attempt to look up a title -- but only when the player is in the presence of the books. The rest of the time such requests should be rejected in the usual way.
+Suppose we want a bookshelf with a very large number of books on it. They aren't to be taken or carried around in the game, but they should be mentioned, and the player should be allowed to look them up by name. Furthermore, the player's attempts to examine something unrecognised should be understood as an attempt to look up a title – but only when the player is in the presence of the books. The rest of the time such requests should be rejected in the usual way.
 
 	{*}"Bibliophilia"
 	
@@ -37,14 +37,19 @@ Suppose we want a bookshelf with a very large number of books on it. They aren't
 	
 	Test me with "south / examine ocd / examine books / examine books / examine plato / n / x hercules / s / x hercules".
 
-Now if we type >X HERCULES in the Lounge, we will get
+Now if we type ``x hercules`` in the Lounge, we will get
 
-	>x hercules
-	You can't see any such thing.
+``` transcript
+>x hercules
+You can't see any such thing.
+```
 
 thanks to our somewhat slovenly implementation of the Lounge scenery; but in the Reading Room,
 
-	>x hercules
-	You can't find any such text.
+``` transcript
+>x hercules
+You can't find any such text.
+```
 
 In practice we might also want to extend our coverage somewhat to handle a case where the player tried to take books from the bookshelf: currently that would not be understood.
+

resources/Documentation/Examples/Bic.txt

@@ -23,3 +23,4 @@ It may occasionally be useful to check whether all objects in our game have a gi
 	The player carries an orange, a Bic pen, and a napkin. The description of the orange is "It's a small hard pinch-skinned thing from the lunch room, probably with lots of pips and no juice."
 	
 	The description of the napkin is "Slightly crumpled."
+

resources/Documentation/Examples/BigSkyCountry.txt

@@ -2,7 +2,7 @@ Example: *** Big Sky Country
 Location: When play ends
 RecipeLocation: Ending The Story
 Index: Resuming play after an accidental death
-Description: Allowing the player to continue play after a fatal accident, but penalizing them by scattering their possessions around the game map.
+Description: Allowing the player to continue play after a fatal accident, but penalising them by scattering their possessions around the game map.
 For: Z-Machine
 
 Some older games allowed the player to be resurrected after a death, but punished them by distributing his possessions far and wide. Here we emulate that effect.
@@ -62,3 +62,4 @@ In a fuller implementation of this game, we might make it possible to get by the
 			try looking.
 
 "If the player consents" is just a convenient way to ask a yes/no question that the player must answer before going on with the game.
+

resources/Documentation/Examples/BikiniAtoll.txt

@@ -16,3 +16,4 @@ For: Z-Machine
 	Test me with "look / examine shell / get shell / look".
 
 (By tradition, and as a courtesy to all the people who have worked on Inform, authors ensure that the banner is printed some time near the beginning of each game played. So please only defer it, rather than suppress it altogether.)
+

resources/Documentation/Examples/Blackout.txt

@@ -25,3 +25,4 @@ Notice that the hyphen in the Absurdly Long-Named Room does not get replaced. We
 		replace the regular expression "\S" in N with "*";
 
 which would catch every character that is not a space.
+

resources/Documentation/Examples/Blankness.txt

@@ -30,3 +30,4 @@ We can tidy this up in the "starting the virtual machine" activity, by temporari
 	Paradise City is a room. The description of Paradise City is "The grass is green and the girls are pretty."
 
 Quite a modest effect, but occasionally useful.
+

resources/Documentation/Examples/Bogart.txt

@@ -5,7 +5,7 @@ Index: Clothing that layers
 Description: Clothing for the player that layers, so that items cannot be taken off in the wrong order, and the player's inventory lists only the clothing that is currently visible.
 For: Z-Machine
 
-We have two things to keep track of with our layering clothing: what currently is covering something else; and what <i>can</i> cover something else. This implementation goes for a fairly simple treatment, assuming that each item of clothing will completely conceal those beneath it, and that we are not implementing entire sets of shirts, jackets, etc. But it will do for a demonstration.
+We have two things to keep track of with our layering clothing: what currently is covering something else; and what *can* cover something else. This implementation goes for a fairly simple treatment, assuming that each item of clothing will completely conceal those beneath it, and that we are not implementing entire sets of shirts, jackets, etc. But it will do for a demonstration.
 
 	{*}"Bogart"
 	
@@ -18,8 +18,8 @@ First we make our relation to represent what *is* underneath another item:
 And now we prevent taking a lower layer off before the thing that is worn over it:
 
 	{**}Before taking off something which underlies something (called the impediment) which is worn by the player:
-	say "(first removing [the impediment])[command clarification break]";
-	silently try taking off the impediment;
+	  say "(first removing [the impediment])[command clarification break]";
+	  silently try taking off the impediment;
 	if the noun underlies something which is worn by the player, stop the action.
 	
 	Check taking off:
@@ -77,3 +77,4 @@ If we further wanted to prevent the player from taking off clothes in inappropri
 
 	Instead of taking off something in the presence of someone who is not the player:
 		say "[We] [are] far too modest to strip in public."
+

resources/Documentation/Examples/Bosch.txt

@@ -2,7 +2,7 @@ Example: * Bosch
 Location: Stored actions
 RecipeLocation: Scoring
 Index: FULL SCORE using a list of stored actions
-Description: Creating a list of actions that will earn the player points, and using this both to change the score and to give FULL SCORE reports.
+Description: Creating a list of actions that will earn the player points, and using this both to change the score and to give ``full score`` reports.
 For: Z-Machine
 
 We could, if we wanted, make a table of stored actions all of which represent things that will earn points for the player. For instance:
@@ -47,3 +47,4 @@ We could, if we wanted, make a table of stored actions all of which represent th
 	Test me with "eat lily / w / full score / get leaf / full".
 
 This system is tidy, but limited: we cannot give actions interesting names in the score list, like "seducing the pirate's daughter" or "collecting a valuable artifact". So it will not be ideal in all situations, but it has the virtue of being easy to extend, and of listing all of the player's successes in the order in which they occurred in their play-through.
+

resources/Documentation/Examples/BostonCream.txt

@@ -137,3 +137,4 @@ For: Z-Machine
 	The maximum score is 1.
 	
 	Test me with "open mesh / get key / unlock case / open case / enter case / close case / lock case / wait / wait".
+

resources/Documentation/Examples/BowlerHatsAndBabyGeese.txt

@@ -2,12 +2,12 @@ Example: *** Bowler Hats and Baby Geese
 Location: During scenes
 RecipeLocation: Scripted Scenes
 Index: Scenes which restrict movement
-Description: Creating a category of scenes that restrict the player's behavior.
+Description: Creating a category of scenes that restrict the player's behaviour.
 For: Z-Machine
 
-Scenes can have properties -- a fact that is very useful when it comes to writing a series of scenes that all need to act alike in some respect.
+Scenes can have properties – a fact that is very useful when it comes to writing a series of scenes that all need to act alike in some respect.
 
-Suppose we have a plot that features a number of scripted scenes, where we need the player to stand still and wait while the events of the scene play out. One way to set this up is to create a property for such scenes -- let's call them "restricted" -- and then write a rule that keeps the player in place while the scene happens:
+Suppose we have a plot that features a number of scripted scenes, where we need the player to stand still and wait while the events of the scene play out. One way to set this up is to create a property for such scenes – let's call them "restricted" – and then write a rule that keeps the player in place while the scene happens:
 
 	{*}"Bowler Hats and Baby Geese"
 	

resources/Documentation/Examples/Bribery.txt

@@ -2,7 +2,7 @@ Example: ** Bribery
 Location: New rules
 RecipeLocation: Barter and Exchange
 Index: GIVE command extended
-Description: A GIVE command that gets rid of Inform's default refusal message in favor of something a bit more sophisticated.
+Description: A ``give`` command that gets rid of Inform's default refusal message in favor of something a bit more sophisticated.
 For: Z-Machine
 
 If we want to rewrite the functionality of a command that usually ends with a "block..." rule, we will have to begin by turning the blocking off.
@@ -11,7 +11,7 @@ If we want to rewrite the functionality of a command that usually ends with a "b
 	
 	The block giving rule is not listed in the check giving it to rules.
 
-As it happens, correct behavior is built into the GIVE command once "block giving" is turned off, so we do not have to write a replacement report or carry-out rule; the object will be transferred to the possession of the caterpillar. But we do want to adjust the action just a little so that our gift cheers up the recipient:
+As it happens, correct behaviour is built into the ``give`` command once "block giving" is turned off, so we do not have to write a replacement report or carry-out rule; the object will be transferred to the possession of the caterpillar. But we do want to adjust the action just a little so that our gift cheers up the recipient:
 
 	{**}Carry out giving (this is the gratitude for gifts rule): improve the mood of the second noun.
 	
@@ -68,3 +68,4 @@ And the rest is all scenario:
 	Understand "forward-up" as up. Understand "forward" as north. Understand "backward" as south.  Understand "backward-down" as down.
 	
 	Test me with "forward / give crumb to caterpillar / forward / forward-up / get aphid / get fragment / down / give aphid to caterpillar / drop aphid / forward-up / get fragment / down / give fragment / forward".
+

resources/Documentation/Examples/Brown.txt

@@ -1,6 +1,6 @@
 Example: *** Brown
 Location: Parts of things
-RecipeLocation: Painting and Labeling Devices
+RecipeLocation: Painting and Labelling Devices
 Index: Red sticky label
 Description: A red sticky label which can be attached to anything in the game, or removed again.
 For: Z-Machine
@@ -14,7 +14,7 @@ For: Z-Machine
 	After examining something when the label is part of the noun:
 		say "A bright red sticky label is attached to [the noun]!"
 
-Here is the essential point: whenever we ATTACH LABEL TO something, it becomes part of that object.
+Here is the essential point: whenever we ``attach label to`` something, it becomes part of that object.
 
 	{**}Instead of tying the red sticky label to something:
 		now the red sticky label is part of the second noun;
@@ -50,8 +50,9 @@ Much of the rest is just tidying to make sure that the player's commands are red
 	
 	Understand the commands "stick" or "apply" as "tie".
 
-We could have created a new "sticking" action, but to keep the example short we will use the built-in "tying" action instead, and respond to the command "stick" just as if it were "tie".
+We could have created a new "sticking" action, but to keep the example short we will use the built-in "tying" action instead, and respond to the command ``stick`` just as if it were ``tie``.
 
 	{**}Understand "peel [something]" or "peel off [something]" as taking.
 	
 	Test me with "i / put label on the black crate / look / x black / x label / get the label / apply label to brown crate / look / x brown / peel off label / stick label to label".
+

resources/Documentation/Examples/BruneseausJourney.txt

@@ -48,3 +48,4 @@ Let's say that our intrepid explorer has a candle that can be lit and blown out
 	Test me with "x candle / light candle / x candle / blow out candle / x candle".
 
 We must be careful: "if the noun was lit" would throw errors because past-tense rules can only be applied to specific items, not to variables that could be anything.
+

resources/Documentation/Examples/BumpingIntoWalls.txt

@@ -28,3 +28,4 @@ There is no theoretical reason why we have to define "count of exits" here: we c
 	The church door is east of Eastern End and west of the Courtyard. The church door is a door.
 	
 	Test me with "u / n / n / e / n / s / u / open door / e / n".
+

resources/Documentation/Examples/CactusWillOutliveUsAll.txt

@@ -24,3 +24,4 @@ If we leave it at that, then pulling the cactus will kill Luckless Luke but then
 		say "That's a real shame."
 	
 	Test me with "get cactus / drop cactus / luke, get cactus / luke, drop cactus / pull cactus / look".
+

resources/Documentation/Examples/CampBethel.txt

@@ -2,18 +2,18 @@ Example: ** Camp Bethel
 Location: Text with random alternatives
 RecipeLocation: Liveliness
 Index: People who do new things each time the player looks
-Description: Creating characters who change their behavior from turn to turn, and a survey of other common uses for alternative texts.
+Description: Creating characters who change their behaviour from turn to turn, and a survey of other common uses for alternative texts.
 For: Z-Machine
 
 	{*}"Camp Bethel"
 	
 	Camp Bethel Kitchen is a room.
 
-One use for text alternatives is to change the description of a room after first visiting. We've already seen, in the example "Slightly Wrong", how to do this with "[if visited] ... [otherwise] ... [end if]". But since the first description is printed once and the second description on all subsequent occasions, we could equally well write
+One use for text alternatives is to change the description of a room after first visiting. We've already seen, in the example [Slightly Wrong], how to do this with "[if visited] ... [otherwise] ... [end if]". But since the first description is printed once and the second description on all subsequent occasions, we could equally well write
 
 	{**}The description of Camp Kitchen is "[one of]You've never been into the kitchen before, though you've spent many an hour in the dining lodge. The place is larger than you would have expected, and it has none of the fake rustic touches of the rest of the camp[or]A tidy, efficient industrial kitchen, without any of the kitsch rusticity found elsewhere[stopping]."
 
-We might also want to liven up the behavior of people and animals, who are probably not doing the exact same thing every time we glance in their direction. There are more complex techniques for modeling the behavior of characters, as we will see in the chapters on Advanced Actions and Activities; but if we just want some textual variety, we might write something like:
+We might also want to liven up the behaviour of people and animals, who are probably not doing the exact same thing every time we glance in their direction. There are more complex techniques for modeling the behaviour of characters, as we will see in the chapters on [Advanced Actions] and [Activities]; but if we just want some textual variety, we might write something like:
 
 	{**}Jeremy is a man in the Camp Bethel Kitchen. "Jeremy stands at his station, [one of]peeling white onions[or]briskly dicing onions[or]chopping celery[or]peeling carrots[or]tying fresh herbs together with string[or]putting all the vegetables into a large stock pot[or]watching over his boiling vegetable stock[cycling]."
 
@@ -29,7 +29,7 @@ Jeremy is following a sequence of actions to do an implied task (still somewhat
 
 The housefly's description is merely "at random" rather than "purely at random" because we want to show it doing a different thing each turn, whereas Fluffy could plausibly stare out the window for five turns in a row.
 
-There are more complex ways to change and override the initial descriptions of people and things; if text alternatives do not get us far enough, we can turn to the "rule for writing a paragraph about," documented in the Activities chapter.
+There are more complex ways to change and override the initial descriptions of people and things; if text alternatives do not get us far enough, we can turn to the "rule for writing a paragraph about," documented in the [Activities] chapter.
 
 Another frequent use of text alternatives is to give characters a bit of variety in things they're likely to say many times in the course of a game:
 
@@ -46,4 +46,5 @@ Notice that, in that last line, our first option is entirely blank. If we put no
 
 	{**}Test me with "look / g / g / g / ask Jeremy about his feelings for me / ask jeremy about his amnesia / tell Jeremy about my unborn child".
 
-As this example (alas) reveals, text alternatives will not go all the way toward making our characters into compelling conversationalists; we will have to wait until we know more about Actions. But at least we have abolished the default responses, and given Jeremy a touch of personality, however witless.
+As this example (alas) reveals, text alternatives will not go all the way toward making our characters into compelling conversationalists; we will have to wait until we know more about actions. But at least we have abolished the default responses, and given Jeremy a touch of personality, however witless.
+

resources/Documentation/Examples/Candy.txt

@@ -22,3 +22,4 @@ Suppose we want to give the player a bag of candies, of which a random one is po
 		now a random piece of candy is poisonous.
 	
 	Test me with "eat candy / g / g / g".
+

resources/Documentation/Examples/CapitalCity.txt

@@ -5,7 +5,7 @@ Index: Capitalised status line
 Description: To arrange that the location information normally given on the left-hand side of the status line appears in block capitals.
 For: Z-Machine
 
-Not much is needed for this. The only noteworthy point is that it doesn't work by changing the LHSL to "[the player's surroundings in upper case]": it cannot do this because "the player's surroundings" is not a value. Instead, "[the player's surroundings]" is a text substitution sometimes printing the name of a room, sometimes printing "Darkness", and so on. We must therefore load it into a text first, and then apply "...in upper case".
+Not much is needed for this. The only noteworthy point is that it doesn't work by changing the left hand status line to `"[the player's surroundings in upper case]"`: it cannot do this because "the player's surroundings" is not a value. Instead, `"[the player's surroundings]"` is a text substitution sometimes printing the name of a room, sometimes printing "Darkness", and so on. We must therefore load it into a text first, and then apply "...in upper case".
 
 	{*}"Capital City"
 	
@@ -20,3 +20,4 @@ Not much is needed for this. The only noteworthy point is that it doesn't work b
 		now the left hand status line is "[the player's capitalised surroundings]".
 	
 	Test me with "e / s / e".
+

resources/Documentation/Examples/Carnivale.txt

@@ -19,7 +19,7 @@ Suppose we want to make an object that (unlike a backdrop) is definitely located
 	
 	The description of Candy Stand is "A hut in pale pink and baby blue dispenses marshmallow death's-heads, sugar-beetles, and other such treats. The giant ferris wheel is just off to the south from here."
 
-As the descriptions make clear, the ferris wheel should be visible from everywhere in the fair, so we'll borrow a line from the Activities chapter to make that happen:
+As the descriptions make clear, the ferris wheel should be visible from everywhere in the fair, so we'll borrow a line from the [Activities] chapter to make that happen:
 
 	{**}After deciding the scope of the player:
 		if the location is in Fairground, place the ferris wheel in scope.
@@ -30,7 +30,7 @@ As the descriptions make clear, the ferris wheel should be visible from everywhe
 
 as it normally would.
 
-Now, by default, if the player were to type TOUCH FERRIS WHEEL while in another room, the story would respond
+Now, by default, if the player were to type ``touch ferris wheel`` while in another room, the story would respond
 
 	You can't reach into By the Wheel.
 
@@ -46,3 +46,4 @@ And because our accessibility rules are considered before the "Instead" phase, w
 		say "You don't dare: it's spinning too fast."
 	
 	Test me with "x ferris wheel / touch ferris wheel / se / x ferris wheel / touch ferris wheel".
+

resources/Documentation/Examples/CasinoBanale.txt

@@ -94,3 +94,4 @@ And finally, we need to give the player a little evidence to piece together:
 		Frince conveys affair-with-Penny.
 	
 	Test me with "x penny / x frince / x shirt / look".
+

resources/Documentation/Examples/Cavetroll.txt

@@ -5,11 +5,11 @@ Index: Modifying and re-parsing an entered command
 Description: Determining that the command the player typed is invalid, editing it, and re-examining it to see whether it now reads correctly.
 For: Z-Machine
 
-Novice players of interactive fiction, unfamiliar with its conventions, will often try to add extra phrases to a command that the game cannot properly parse: HIT DOOR WITH FIST, for instance, instead of HIT DOOR.
+Novice players of interactive fiction, unfamiliar with its conventions, will often try to add extra phrases to a command that the game cannot properly parse: ``hit door with fist``, for instance, instead of ``hit door``.
 
 While we can deal with some of these instances by expanding our range of actions, at some point it becomes impossible to account for all the possible prepositional phrases that the player might want to tack on. So what do we do if we want to handle those appended bits of text sensibly?
 
-We could go through and remove any piece of text containing "with ..." from the end of a player's command; the problem with that is that it overzealously lops off the ends of valid commands like UNLOCK DOOR WITH KEY, as well. So clearly we don't want to do this as part of the "After reading a command..." stage.
+We could go through and remove any piece of text containing "with ..." from the end of a player's command; the problem with that is that it overzealously lops off the ends of valid commands like ``unlock door with key``, as well. So clearly we don't want to do this as part of the "After reading a command..." stage.
 
 A better time to cut off the offending text is right before issuing a parser error. At that point, Inform has already determined that it definitely cannot parse the instruction as given, so we know that there's something wrong with it.
 
@@ -51,4 +51,5 @@ Thanks to John Clemens for the specifics of the implementation.
 	
 	Test me with "attack troll with sword / unlock chest with sword / attack troll as a test".
 
-A caveat about using this method in a larger game: "parser error flag" will not automatically control the behavior of any rules we might have written for Before reading a command... or After reading a command..., so they may now fire at inappropriate times. It is a good idea to check for parser error flag in those rules as well.
+A caveat about using this method in a larger game: "parser error flag" will not automatically control the behaviour of any rules we might have written for Before reading a command... or After reading a command..., so they may now fire at inappropriate times. It is a good idea to check for parser error flag in those rules as well.
+

resources/Documentation/Examples/Celadon.txt

@@ -5,9 +5,9 @@ Index: DROP applies even to objects the player carries indirectly
 Description: Using the enclosure relation to let the player drop things which they only indirectly carry.
 For: Z-Machine
 
-By default, Inform only lets the player drop those things which they are carrying -- that is, those directly in their possession. Things inside satchels or on portable trays have to be taken first.
+By default, Inform only lets the player drop those things which they are carrying – that is, those directly in their possession. Things inside satchels or on portable trays have to be taken first.
 
-If we want to change this behavior, we might add a dropping rule that distinguishes between carrying and mere enclosure (introduced back in "The location of something" in the chapter on Things):
+If we want to change this behaviour, we might add a dropping rule that distinguishes between carrying and mere enclosure (introduced back in "The location of something" in the chapter on [Things]):
 
 	{*}"Celadon"
 	
@@ -23,3 +23,4 @@ If we want to change this behavior, we might add a dropping rule that distinguis
 		say "It seems to be stuck to the tray, possibly by an underlying wad of gum."
 	
 	Test me with "i / drop teapot / i / look / drop teapot / drop napkin / i / drop tray".
+

resources/Documentation/Examples/Centered.txt

@@ -5,6 +5,8 @@ Index: Status line with centered text, the easy way
 Description: Replacing the two-part status line with one that centers only the room name at the top of the screen.
 For: Z-Machine
 
+[ZL: "included as part of the standard distribution..."]::
+
 If we want to lay out the status line in some other way than with left-hand and right-hand entries, it is possible to do this as well. Later we will learn about the "rule for constructing the status line", but here is a basic effect using this rule and an Inform extension included as part of the standard distribution, called Basic Screen Effects.
 
 	{*}"Centered"
@@ -25,3 +27,4 @@ If we want to lay out the status line in some other way than with left-hand and
 	Test me with "look".
 
 Basic Screen Effects also provides a mechanism for building complicated status lines of more than one row. To read its documentation, we include the extension, press Go!, and then consult the contents index that results.
+

resources/Documentation/Examples/ChanelVersion1-G.txt

@@ -5,7 +5,7 @@ Index: HTML-style italic and boldface tags
 Description: Making paired italic and boldface tags like those used by HTML for web pages.
 For: Glulx
 
-HTML uses angled brackets to achieve effects, and places italicised text between <i> and </i> tags; and similarly boldface between <b> and </b>. We can mimic this very easily by setting each up as a segmented substitution:
+HTML uses angled brackets to achieve effects, and places italicised text between <i> and </i> tags; and similarly boldface between <b> and </b>. We can mimic this very easily by setting each up as a segmented substitution:
 
 	{*}"Chanel Version 1"
 	
@@ -23,3 +23,4 @@ HTML uses angled brackets to achieve effects, and places italicised text between
 We have had to use square instead of angle brackets, but then, "in order to be irreplaceable one must always be different" (Coco Chanel).
 
 (Marking these as substitutions which run on prevents unexpected paragraph breaks if they should appear immediately after the end of a sentence.)
+

resources/Documentation/Examples/ChangeOfBasis.txt

@@ -35,3 +35,4 @@ Now a few rules about changing from one state to the other:
 		say "You'd really rather just sleep through this."
 	
 	Test me with "wake up / sleep / look / z / sleep / wake up / look".
+

resources/Documentation/Examples/Channel1.txt

@@ -1,5 +1,4 @@
 Example: ** Channel 1
-Subtitle: Television that can be referred to by channel
 Location: Understanding things by their properties
 RecipeLocation: Televisions and Radios
 Index: Channel 1. Television that can be referred to by channel
@@ -8,8 +7,8 @@ For: Z-Machine
 
 We might want to allow every television to be tuned to a channel (a number property) which the player could refer to, so that
 
-	WATCH CHANNEL 13
-	TURN OFF CHANNEL 4
+- ``watch channel 13``
+- ``turn off channel 4``
 
 would be directed to the appropriate television object, if any television is turned on and tuned to the correct station. We might now write:
 

resources/Documentation/Examples/Channel2.txt

@@ -1,26 +1,17 @@
 Example: *** Channel 2
-Subtitle: Television with more advanced parsing
 Location: Understanding things by their properties
 RecipeLocation: Televisions and Radios
 Index: Channel 2. Television with more advanced parsing
 Description: Understanding channels (a number) in the names of televisions, with more sophisticated parsing of the change channel action.
 For: Z-Machine
 
-Our previous implementation of televisions ("Channel 1") doesn't allow the player to type things like
+[ZL: I took more liberties here than usual; please review.]::
 
-	TUNE FIFTIES TELEVISION TO CHANNEL 4
+Our previous implementation of televisions ([Channel 1]) doesn't accept ``tune fifties television to channel 4``; neither does it deal with player input like ``tune to channel 4 on fifties television``, nor ``tune to channel 4`` where no television is specified.
 
-nor does it deal with player input like
+When we are designing commands which involve two elements (here, a television and a channel number), it's usually a good idea to allow the player to specify those elements in either order, as we saw demonstrated briefly in [New commands for old grammar].
 
-	TUNE TO CHANNEL 4 ON FIFTIES TELEVISION
-
-or
-
-	TUNE TO CHANNEL 4
-
-where no television is specified. When we are designing commands which involve two elements (here, a television and a channel number), it's usually a good idea to allow the player to specify those elements in either order, as we saw demonstrated briefly in "New commands for old grammar".
-
-We might, therefore, want to add a few refinements: first by defining a "[channel]" token that will accept input of the forms "[number]" and "channel [number]", and second by creating some additional "Understand" lines that will accept variant versions of the player's input.
+We might, therefore, want to add a few refinements: first by defining a `"[channel]"` token that will accept input of the forms `"[number]"` and "channel [number]", and second by creating some additional "Understand" lines that will accept variant versions of the player's input.
 
 	{*}"Channel 2"
 	

resources/Documentation/Examples/Cheesemakers.txt

@@ -2,12 +2,12 @@ Example: *** Cheese-makers
 Location: Why are scenes designed this way?
 RecipeLocation: Saying Complicated Things
 Index: TALK TO command used with scenes
-Description: Scenes used to control the way a character reacts to conversation and comments, using a TALK TO command.
+Description: Scenes used to control the way a character reacts to conversation and comments, using a ``talk to`` command.
 For: Z-Machine
 
 As we have seen, there are a number of different ways of controlling conversation in interactive fiction, and the best choice of way will depend quite a lot on what kind of work we're writing.
 
-One common model is to replace Inform's default ASK and TELL commands with a TALK TO command. This gives the player less control than they would otherwise have: instead of asking a character about any topic under the sun, they're restricted to seeing (or not seeing) a single sequence of text that the author has written in advance. On the other hand, such a system is harder for the player to break (since they can never ask about a topic that the author hasn't implemented), and easier for the author to tie into plot developments. If we give TALK TO different output at each scene, we get conversation that is always tied to the current state of the plot.
+One common model is to replace Inform's default ``ask`` and ``tell`` commands with a ``talk to`` command. This gives the player less control than they would otherwise have: instead of asking a character about any topic under the sun, they're restricted to seeing (or not seeing) a single sequence of text that the author has written in advance. On the other hand, such a system is harder for the player to break (since they can never ask about a topic that the author hasn't implemented), and easier for the author to tie into plot developments. If we give ``talk to`` different output at each scene, we get conversation that is always tied to the current state of the plot.
 
 This is a design approach that works best in a game with a large number of short, focused scenes. For other kinds of conversation system design, compare the other examples listed in the Recipe Book.
 
@@ -15,7 +15,7 @@ This is a design approach that works best in a game with a large number of short
 	
 	Chapter 1 - Replacing old talk commands and making a new one
 
-Here, using some techniques that will be discussed in the chapter on Understanding, we get rid of Inform's default handling of ASK and TELL, and create our own TALK TO action instead:
+Here, using some techniques that will be discussed in the chapter on [Understanding], we get rid of Inform's default handling of ``ask`` and ``tell``, and create our own ``talk to`` action instead:
 
 	{**}Understand the commands "ask" and "tell" and "say" and "answer" as something new.
 	
@@ -34,7 +34,7 @@ Here, using some techniques that will be discussed in the chapter on Understandi
 	
 	Chapter 2 - Specific scenes and talking
 
-Now, suppose we have a situation -- say, a stage play -- in which it is appropriate to talk to different characters at different times. During the prologue of the play, no one else is on-stage, and the player is to address the audience directly:
+Now, suppose we have a situation – say, a stage play – in which it is appropriate to talk to different characters at different times. During the prologue of the play, no one else is on-stage, and the player is to address the audience directly:
 
 	{**}Section 1 - Prologue
 	
@@ -89,7 +89,7 @@ But there might follow a scene in which the player shouldn't talk at all:
 	"You stand aside as the chorus fills the orchestra and dances to and fro."
 	"The tune of the aulos-player grows more and more frenzied and then breaks off."
 
-This last rule is a refinement borrowing from the Activities chapter, which gives characters different appearances in room descriptions depending on when we happen to look; because of the action of the play, we want to show the chorus and audience doing different things during different scenes.
+This last rule is a refinement borrowing from the [Activities] chapter, which gives characters different appearances in room descriptions depending on when we happen to look; because of the action of the play, we want to show the chorus and audience doing different things during different scenes.
 
 	{**}Rule for writing a paragraph about the chorus during Parodos:
 		say "The chorus are dancing and singing their way[if the time since Parodos began is less than 3 minutes] up the long walkways onto the stage[otherwise] into position in the orchestra[end if]. [The audience] appear to be pricing their costumes to the nearest obol: woe to the producer who cheats them of their due share of spectacle."

resources/Documentation/Examples/ChronicHintingSyndrome.txt

@@ -182,3 +182,4 @@ Now suppose that as an added convenience for the player, we let them turn on a m
 	"[Nathan] makes an explosive exasperated sound. 'Don't you want to ask me about [the random pending subject]?' he demands."
 	
 	Test me with "highlighting bright / put sculpture on pedestal / put it on table / put it on sickbed / drop it / think / ask nathan about breakage / think / ask him about generator / ask him about dreams / ask him about gift / ask him about shari / ask him about scar".
+

resources/Documentation/Examples/Cinco.txt

@@ -31,3 +31,4 @@ It's fairly common that we want to be able to refer to a container in terms of w
 		say "You gingerly pick [the noun] out of the taco shell." instead.
 	
 	Test me with "x taco / put shredded beef in taco / get taco / i / x shredded beef taco / get shredded beef / x shredded beef taco".
+

resources/Documentation/Examples/CircleOfMisery.txt

@@ -36,3 +36,4 @@ The list "circle of misery" is our ring, in which entry 1 is considered to be th
 	Instead of inserting something into the carousel, say "In recent years, the authorities have tended to frown upon depositing bags in random places at airports."
 	
 	Test me with "get suitcase / get suitcase / get suitcase / get suitcase / look / get golf bag / look / get golf bag".
+

resources/Documentation/Examples/ClaimsAdjustment.txt

@@ -7,7 +7,7 @@ For: Z-Machine
 
 We start by creating a camera and a photograph object. As usual when we want to have a kind of object that can be dispensed in bulk, we start off with a bunch of identical instances of the object out of play (in this case, kept in an out-of-play container called "film roll"); we can then move them into play and give them characteristics when they're needed.
 
-Each photograph can depict exactly one thing -- we're assuming that the player is not a landscape photographer here -- so we create a relation to indicate what is shown by each photograph. We'll then use that relation to determine how photographs are described, named, and parsed:
+Each photograph can depict exactly one thing – we're assuming that the player is not a landscape photographer here – so we create a relation to indicate what is shown by each photograph. We'll then use that relation to determine how photographs are described, named, and parsed:
 
 	{*}"Claims Adjustment"
 	
@@ -49,7 +49,7 @@ Now we create an action to let the player use the camera and generate these phot
 	Report photographing:
 		say "Your camera instantly spits out [a selected film]."
 
-Now we use two activities from the Activities chapter to describe the photographs to the player more elegantly:
+Now we use two activities from the [Activities] chapter to describe the photographs to the player more elegantly:
 
 	{**}After printing the name of a photograph (called target):
 		say " of [a random thing which is shown by the target]".
@@ -70,3 +70,4 @@ And finally we provide a brief scenario to give the player something to take pic
 	Test me with "photograph degas / i / photograph degas / i / x photograph of degas / photograph me / x photograph of me / i / photograph vase / photograph camera / photograph collection / g / i / test more".
 	
 	Test more with "x photograph of collection / x photograph of krugerrands / x photograph of collection of south african krugerrands / photograph photograph of degas / x photograph of photograph of degas".
+

resources/Documentation/Examples/CloakOfDarkness.txt

@@ -91,4 +91,5 @@ This defines an object which is worn at the start of play. Because we have said
 	
 	Test me with "s / n / w / inventory / hang cloak on hook / e / s / read message".
 
-And that's all. As always, type TEST ME to watch the scenario play itself out.
+And that's all. As always, type ``test me`` to watch the scenario play itself out.
+

resources/Documentation/Examples/Cloves.txt

@@ -7,7 +7,7 @@ For: Z-Machine
 
 It has sometimes been suggested that IF should allow for the player to use adverbs, so that doing something "carefully" will have a different effect from doing it "quickly". There are several inherent challenges here: it's a good idea to make very sure the player knows all their adverb options, and the list of possibilities should probably not be too long.
 
-Another trick is that adverbs complicate understanding commands, because they can occur anywhere: one might type >GO WEST CAREFULLY or >CAREFULLY GO WEST, and ideally the game should understand both. After reading a command is the best point to do this sort of thing, because we can find adverbs, interpret them, and remove them from the command stream. So:
+Another trick is that adverbs complicate understanding commands, because they can occur anywhere: one might type ``go west carefully`` or ``carefully go west``, and ideally the game should understand both. After reading a command is the best point to do this sort of thing, because we can find adverbs, interpret them, and remove them from the command stream. So:
 
 	{*}"Cloves"
 	
@@ -59,4 +59,5 @@ Now we have, automatically, a value called manner understood to be used whenever
 
 The qualification about turn count is to prevent this before message from occurring when the player first looks around the room (automatically) at the start of play.
 
-Note that to test this example, one must type INSOUCIANTLY TEST ME, and not simply TEST ME: a poseur's work is never done.
+Note that to test this example, one must type ``insouciantly test me``, and not simply ``test me``: a poseur's work is never done.
+

resources/Documentation/Examples/Clueless.txt

@@ -5,7 +5,7 @@ Index: Murderer chosen randomly at start of play
 Description: A murderer for the mystery is selected randomly at the beginning of the game.
 For: Z-Machine
 
-"When play begins" is the best point to initialize any aspects of the game that are meant to change between playings. For instance, in this scenario, we would randomly select one of the other characters to be guilty of murder:
+"When play begins" is the best point to initialise any aspects of the game that are meant to change between playings. For instance, in this scenario, we would randomly select one of the other characters to be guilty of murder:
 
 	{*}"Clueless"
 	
@@ -20,3 +20,4 @@ For: Z-Machine
 		say "[The noun] certainly looks fiendish!"
 	
 	Test me with "x mustard / x plum / x scarlet / x white".
+

resources/Documentation/Examples/ComplimentaryPeanuts.txt

@@ -30,7 +30,7 @@ The topic understood is also a snippet, so that whenever one has been generated,
 				rule succeeds;
 		say "'Hmmf,' says Aunt Martha."
 
-This is superior to checking "the player's command" because we do not want ASK MARTHA ABOUT FRENCH FRIES to trigger the "Martha" keyword, only the "french fries" keywords.
+This is superior to checking "the player's command" because we do not want ``ask martha about french fries`` to trigger the "Martha" keyword, only the "french fries" keywords.
 
 	{**}The Empyrean Shuttle Bay is a room. "From here you have an excellent view of the colony world, which looks... well, it looks discouragingly orange. But terraforming is in progress."
 	
@@ -46,13 +46,16 @@ This is superior to checking "the player's command" because we do not want ASK M
 
 This means that Martha will respond to keywords regardless of the setting in which they occur. For instance:
 
-	>martha, get in the shuttle
-	"Shuttles! I hate shuttles," Aunt Martha grumbles. "Give me an airplane! AIRPLANE."
+``` transcript
+>martha, get in the shuttle
+"Shuttles! I hate shuttles," Aunt Martha grumbles. "Give me an airplane! AIRPLANE."
 
-	>martha, for pity's sake, do you see an airplane around here?
-	"Those were the days," Aunt Martha agrees, plainly reliving the days when she wore a blue-and-white uniform and passed out packets of salted peanuts.
+>martha, for pity's sake, do you see an airplane around here?
+"Those were the days," Aunt Martha agrees, plainly reliving the days when she wore a blue-and-white uniform and passed out packets of salted peanuts.
 
-	>martha, pass me the rations
-	"Do you think there are any peanuts in there?" she asks in a wistful tone.
+>martha, pass me the rations
+"Do you think there are any peanuts in there?" she asks in a wistful tone.
+```
 
 This is not the stuff of which Loebner-winning chatbots are made, admittedly, but it is occasionally a useful alternative to stricter modes of command-parsing.
+

resources/Documentation/Examples/ControlCenter.txt

@@ -5,7 +5,7 @@ Index: Describing objects with parts
 Description: Objects which automatically include a description of their component parts whenever they are examined.
 For: Z-Machine
 
-It is straightforward to make a rule that anything with parts must mention all those parts during an EXAMINE command:
+It is straightforward to make a rule that anything with parts must mention all those parts during an ``examine`` command:
 
 	{*}"Control Center"
 	

resources/Documentation/Examples/CopperRiver.txt

@@ -7,7 +7,7 @@ For: Z-Machine
 
 In a very dense environment, we might want to offer the player room descriptions in which only the currently-interesting items are mentioned, while other objects are suppressed even if they are present. In effect, this takes the idea of scenery and makes it more flexible: different things might become background objects or foreground objects at different times during play.
 
-There are a wide range of possible reasons to do this -- to shift the narrative emphasis, to change the mood of the game by highlighting different parts of the environment, to show the game from the perspective of different viewpoint characters -- but in the following example, our goal is to show the player only the objects that are currently useful for puzzles.
+There are a wide range of possible reasons to do this – to shift the narrative emphasis, to change the mood of the game by highlighting different parts of the environment, to show the game from the perspective of different viewpoint characters – but in the following example, our goal is to show the player only the objects that are currently useful for puzzles.
 
 To do this, we need some notion of what puzzles are currently available and unsolved, so we make an "unsolved" adjective; we also need to know which things solve the puzzle, so we create a "resolving" relation, to indicate which objects resolve which problems.
 
@@ -82,7 +82,6 @@ Given that information, we can create rules about which objects in the game worl
 	
 	Rule for grouping together dull things: say "assorted dull items".
 	
-
 	Section 2 - Scenario World and Objects
 	
 	The Kitchen is a room. "Your Aunt Fiona's kitchen looks as though it has been at the eye of a glitter storm. Fine, sparkling grit dusts every surface. The appliances are slightly askew, too, as though they hadn't quite settled after a vigorous earthquake."

resources/Documentation/Examples/CornerOfNoAndWhere.txt

@@ -39,4 +39,5 @@ Making major changes to display features, such as the construction of the status
 	
 	Test me with "w / e".
 
-In fact, as we've already seen, many extra modifications to the display behavior are possible using Basic Screen Effects.
+In fact, as we've already seen, many extra modifications to the display behaviour are possible using Basic Screen Effects.
+

resources/Documentation/Examples/CostaRicanOrnithology.txt

@@ -30,13 +30,13 @@ We will come back to the idea of tables and table names later, but for now the i
 	"[red]" or "[red] bird/macaw"	"You flip through the Guide for a while and eventually discover a reference to the [scarlet macaw], which appears to correspond with what you see before you."
 	"quetzal/trogon" or "resplendent trogon"	"The entry on the quetzal is quite lyrical, describing its brilliant plumage, flashing and igniting in the sunshine, which is supposedly sufficient to lure birdwatchers from all over the world. Unfortunately, the quetzal is described as being bright emerald in color, with a pink fuzz on its head and a long soft tail 'like a feather boa'. None of these describes your visitor."
 
-The topic column is a bit special: it matches the player's input, and is not meant to be printed out again. Topic columns will be discussed further in the chapter on Tables. (Note also that, however it may appear in the documentation, the topic column should not be spanning multiple lines in our source text.)
+The topic column is a bit special: it matches the player's input, and is not meant to be printed out again. Topic columns will be discussed further in the chapter on [Tables]. (Note also that, however it may appear in the documentation, the topic column should not be spanning multiple lines in our source text.)
 
 We may also compress long or complicated topics by creating bracketed abbreviations, and in fact it's useful to do so now, to explain the red token we just used:
 
 	{**}Understand "red-orange" or "bird" or "red" or "orange" as the scarlet macaw. Understand "red-orange" or "red" or "orange" or "scarlet" as "[red]".
 
-This technique is discussed further in the chapter on Understanding.
+This technique is discussed further in the chapter on [Understanding].
 
 If we wanted more books, we could define those in the same way, giving each its own separate contents table to be used for consultation. But for the sake of the example we will keep it simple, and move on to the scenario itself:
 
@@ -52,3 +52,4 @@ If we wanted more books, we could define those in the same way, giving each its
 	Rule for printing the name of the unknown scarlet macaw: if the macaw is unknown, say "red-orange bird of unknown species".
 	
 	Test me with "look up penguins in the guide / look up quetzal in guide / look up silver nuthatches in the guide / look / look up red bird in the book / look".
+

resources/Documentation/Examples/Croft.txt

@@ -5,7 +5,7 @@ Index: DROPPING into and onto things
 Description: Adding special reporting and handling for objects dropped when the player is on a supporter, and special entering rules for moving from one supporter to another.
 For: Z-Machine
 
-Suppose that we have a design in which the player spends lots of time on enterable supporters, and in which we want to report certain actions -- dropping things onto those supporters, or leaping from one to another -- in a new way. We might begin by adding some action variables to help us keep track of the situation:
+Suppose that we have a design in which the player spends lots of time on enterable supporters, and in which we want to report certain actions – dropping things onto those supporters, or leaping from one to another – in a new way. We might begin by adding some action variables to help us keep track of the situation:
 
 	{*}"Croft"
 	
@@ -64,3 +64,4 @@ Because this rule occurs before the "implicitly pass through other barriers rule
 	Instead of climbing a platform, try entering the noun.
 	
 	Test me with "Lara, drop map / lara, drop gun / drop idol / enter bronze platform / drop pickaxe / get off / climb wood".
+

resources/Documentation/Examples/Crusoe.txt

@@ -7,7 +7,7 @@ For: Z-Machine
 
 Suppose we want to add rules so that any time we examine a charred object (and most of our objects can be charred), a line about the charring is appended to the end of the object description. We could use "after examining...", but perhaps we would prefer for the sentence about the charring not to appear in its own paragraph.
 
-This is an ideal occasion for a new activity. We look at the action index for "examining" to identify the rule that causes the old behavior (in this case, the "standard examining rule"); replace this with a new rule that calls our activity; and write our "printing the description" activity in such a way that it uses an object's description without forcing a paragraph return afterward.
+This is an ideal occasion for a new activity. We look at the action index for "examining" to identify the rule that causes the old behaviour (in this case, the "standard examining rule"); replace this with a new rule that calls our activity; and write our "printing the description" activity in such a way that it uses an object's description without forcing a paragraph return afterward.
 
 Then we will use "after printing the description" to add our line about charring, and make sure that the paragraph return does occur before the prompt.
 
@@ -19,7 +19,7 @@ So:
 	
 	The fancy examining rule is listed instead of the standard examining rule in the carry out examining rules.
 
-This instruction replaces a normal piece of the examine action, the standard examining rule, with another one of our own devising. (The replacement of the standard examining rule will be explained in more detail in the chapter on rulebooks.)
+This instruction replaces a normal piece of the examine action, the standard examining rule, with another one of our own devising. (The replacement of the standard examining rule will be explained in more detail in the chapter on [Rulebooks].)
 
 	{**}Printing the description of something is an activity.
 	
@@ -27,7 +27,7 @@ This instruction replaces a normal piece of the examine action, the standard exa
 		carry out the printing the description activity with the noun;
 		rule succeeds.
 
-All we have done here is enclose what is usually just a rule inside an activity. This means that we can now write before and after rules for the activity, and also add special instructions like "Rule for printing the name of something while printing the description of something" -- this may not be likely to arise often, but Inform now has the concept of "printing the description of something" as a separate context of action. Next we add the modification that lets us append to the description without a new line:
+All we have done here is enclose what is usually just a rule inside an activity. This means that we can now write before and after rules for the activity, and also add special instructions like "Rule for printing the name of something while printing the description of something" – this may not be likely to arise often, but Inform now has the concept of "printing the description of something" as a separate context of action. Next we add the modification that lets us append to the description without a new line:
 
 	{**}Rule for printing the description of something (called item):
 		if the description of the item is not "":
@@ -44,7 +44,7 @@ The instead at the end of this line stops Inform for going on with any other "af
 
 The standard library also has rules for printing additional text about containers and supporters with visible contents, and devices that are switched on; with this current system, we could add those as "after printing the description" rules as well, building up a complete paragraph if we wanted. But for simplicity we won't exemplify all of that here. The effects would be much the same as with the "charred" line.
 
-Now, because we want to make sure that we always do get a paragraph break after our description, we add this rule last after all the other rules. "Last" and "first" rules are covered in more detail in the chapter on rulebooks.
+Now, because we want to make sure that we always do get a paragraph break after our description, we add this rule last after all the other rules. "Last" and "first" rules are covered in more detail in the chapter on [Rulebooks].
 
 	{**}Last after printing the description of something:
 		say paragraph break.
@@ -73,3 +73,4 @@ The player's description is handled in an unusual way, and this will produce a s
 	Test me with "i / x stick / x bottle / x sand / x paper / x me / burn stick / x stick / burn paper / x paper".
 
 The "printing a description" activity may be useful for other games, and can be imported just by lifting section 1.
+

resources/Documentation/Examples/Curare.txt

@@ -1,7 +1,7 @@
 Example: * Curare
 Location: Descriptions as values
 RecipeLocation: Varying What Is Written
-Index: Cyclical randomization of named objects
+Index: Cyclical randomisation of named objects
 Description: A phrase that chooses and names the least-recently selected item from the collection given, allowing the text to cycle semi-randomly through a group of objects.
 For: Z-Machine
 
@@ -23,10 +23,11 @@ This phrase will select, from the collection of objects passed to it, the one th
 	{**}After taking inventory:
 		say "You stare morosely at [the cyclically random thing carried by the player], wondering what you're ever going to find to do with it."
 
-We could have said "You stare morosely at [the oldest thing carried by the player]" here, but doing so would not have set the "last use" property correctly, so we would not get the cycling behavior that we're looking for.
+We could have said "You stare morosely at [the oldest thing carried by the player]" here, but doing so would not have set the "last use" property correctly, so we would not get the cycling behaviour that we're looking for.
 
 	{**}The Evidence Room is a room. Some shelves are scenery supporters in the Evidence Room. A box is a kind of container which is open and not openable. On the shelves is a box.  It contains a deformed bullet and a driver's license.
 	
 	The player carries a steel fish hook, a Chinese passport, a tube of synthetic curare, and an envelope full of Euros.
 	
 	Test me with "i / i / i / i / i / i / get all from box / i / i / i".
+

resources/Documentation/Examples/DayOne.txt

@@ -49,7 +49,7 @@ And to add a few additional details:
 	{**}Instead of doing something other than waiting, looking, listening or examining during Lecture:
 		say "Dr Freitag glares at you so fiercely that you are frozen into inaction."
 
-Notice the careful phrasing of "doing something other than..." so that we do not mention the objects; if we had written "something other than listening to something...", the instead rule would match only action patterns which involved a noun. We state the rule more generally so that it will also match nounless commands such as JUMP and SING, since Freitag will probably take a dim view of those as well.
+Notice the careful phrasing of "doing something other than..." so that we do not mention the objects; if we had written "something other than listening to something...", the instead rule would match only action patterns which involved a noun. We state the rule more generally so that it will also match nounless commands such as ``jump`` and ``sing``, since Freitag will probably take a dim view of those as well.
 
 	{**}When Lecture ends:
 		now Freitag is nowhere;
@@ -58,3 +58,4 @@ Notice the careful phrasing of "doing something other than..." so that we do not
 	The Classroom is a room. Dr Freitag is a man in the Classroom. "Dr Freitag paces before the blackboard."
 	
 	Test me with "listen / x dr / x me / jump / z / z / z / z / z / x dr".
+

resources/Documentation/Examples/DearthAndTheMaiden.txt

@@ -1,7 +1,7 @@
 Example: * Dearth and the Maiden
 Location: Kinds of action
-RecipeLocation: Characterization
-Index: Restrictions preventing inappropriate behavior
+RecipeLocation: Characterisation
+Index: Restrictions preventing inappropriate behaviour
 Description: Our heroine, fallen among gentleman highwaymen, is restrained by her own modesty and seemliness.
 For: Z-Machine
 
@@ -20,3 +20,4 @@ The following example, indebted to the late Georgette Heyer, is suggestive:
 	Instead of unmaidenly behaviour in the Inn, say "How unmaidenly! Why, one might just as wantonly strip a rose of its petals, letting each fragrant leaf flutter slowly to the ground."
 	
 	Test me with "examine painting / take painting / kiss mr carr".
+

resources/Documentation/Examples/DelayedGratification.txt

@@ -2,7 +2,7 @@ Example: ** Delayed Gratification
 Location: Named rules and rulebooks
 RecipeLocation: Waiting, Sleeping
 Index: WAIT UNTIL [time] command
-Description: A WAIT UNTIL [time] command which advances until the game clock reaches the correct hour.
+Description: A ``wait until`` [time] command which advances until the game clock reaches the correct hour.
 For: Z-Machine
 
 	{*}"Delayed Gratification"
@@ -29,3 +29,4 @@ For: Z-Machine
 		end the story finally.
 	
 	Test me with "look / z / z / wait until 11:45 PM".
+

resources/Documentation/Examples/DeliciousDeliciousRocks.txt

@@ -7,9 +7,11 @@ For: Z-Machine
 
 In some cases, we may want to add new stages to action processing. One possibility is a stage where we check the sanity of what the player is trying to do before executing any of the other commands; so that we avoid, for instance
 
-	>EAT ROCK
-	(first taking the rock)
-	That's plainly inedible.
+``` transcript
+>eat rock
+(first taking the rock)
+That's plainly inedible.
+```
 
 Here is how we might insert such a stage in our action processing, using rulebook manipulation.
 
@@ -41,3 +43,4 @@ It is of course possible to get the same effect with
 		say "Your digestion is so delicate -- you're sure [the noun] wouldn't agree with you." instead.
 
 ...and in a small game with few rules, there's not much reason to add an extra stage. The ability to modify the stages of action processing becomes useful when we have a fairly large game with sophisticated modeling and want to be sure that some kinds of message (such as the sanity-check) are always handled before other things that we might be doing at the before stage (such as generating implicit actions like opening doors before going through them).
+

resources/Documentation/Examples/DemocraticProcess.txt

@@ -2,9 +2,11 @@ Example: *** Democratic Process
 Location: Before rules
 RecipeLocation: Taking, Dropping, Inserting and Putting
 Index: PUT and INSERT automatically TAKE first
-Description: Make PUT and INSERT commands automatically take objects if the player is not holding them.
+Description: Make ``put`` and ``insert`` commands automatically take objects if the player is not holding them.
 For: Z-Machine
 
+[ZL: https://inform7.atlassian.net/browse/I7-2348 This refers to outdated behaviour ]::
+
 "Stop" and "Continue" are most useful when we need to write rules that will have to stop the action some of the time but at other times let it pass; so for instance:
 
 	{*}"Democratic Process"

resources/Documentation/Examples/Depth.txt

@@ -48,7 +48,7 @@ When testing this example, the author made use of the following: it's no longer
 		say "[the item] - height [height of the item], width [width of the item], depth [depth of the item].";
 		say "largest side [largest dimension of the item], middling [middling dimension of the item], smallest [shortest dimension of the item]."
 
-We now introduce a new kind: a measured container, which not only has exterior dimensions - the height, width and depth which every thing now has - but also interior measurements. A convenient way to do calculations with the hollow interior is to regard it as if it were a solid shape in its own right, and we do this with the aid of something out of world, which the player never sees: the "imaginary cuboid", which is made into the shape of whatever measured container's interior is being thought about.
+We now introduce a new kind: a measured container, which not only has exterior dimensions–the height, width and depth which every thing now has–but also interior measurements. A convenient way to do calculations with the hollow interior is to regard it as if it were a solid shape in its own right, and we do this with the aid of something out of world, which the player never sees: the "imaginary cuboid", which is made into the shape of whatever measured container's interior is being thought about.
 
 	{**}A measured container is a kind of container. A measured container has a length called interior height. A measured container has a length called interior width. A measured container has a length called interior depth.
 	
@@ -101,3 +101,4 @@ And finally a situation to try out these rules.
 Several warnings about this. First, the numbers can't go very high (if the Settings for the project set the story file format to the Z-machine): while the volume can in theory go to 32,767, in practice this equates to an object 32 cm on a side, which is not very large. One way to avoid this is to use the Glulx format, allowing for sizes in excess of 10 m on a side: or we could simply scale the dimensions to suit our purposes, using a decimeter (10 cm) as the basic unit of measurement, for instance.
 
 Second, the system will require a height, width, and depth for every portable object in the game, which is a large commitment to data entry; it may become tiresome. So it is probably not worth bothering with this kind of simulation unless it is going to be genuinely significant.
+

resources/Documentation/Examples/Dimensions.txt

@@ -28,3 +28,4 @@ The following is not a very sophisticated approach, because it does not allow fo
 	The balance platform is a supporter in the Weighbridge. "The balance platform is 10m by 8m, giving it an area of [10m multiplied by 8m], currently weighing [the list of things on the platform]. The scale alongside reads: [total weight of things on the platform]. [if two things are on the platform]Average weight is: [the total weight of things on the platform divided by the number of things on the platform]. Heaviest item is [the heaviest thing on the platform], at [weight of the heaviest thing on the platform]. Lightest item is [the lightest thing on the platform], at [weight of the lightest thing on the platform].[otherwise]It seems to be able to weigh several things at once."
 	
 	Test me with "get feather / put it on platform / look / get pig / put it on platform / look".
+

resources/Documentation/Examples/DinnerIsServed.txt

@@ -55,3 +55,4 @@ And the rest is window-dressing.
 		if the player is in the Shop, place the Street in scope.
 	
 	Test me with "examine shop / open refrigerator / open window / examine shop / open refrigerator / get beer / in / examine street / out / get gyro / close window / put gyro in refrigerator / open window / put gyro in refrigerator".
+

resources/Documentation/Examples/DisenchantmentBay1.txt

@@ -1,5 +1,4 @@
 Example: * Disenchantment Bay 1
-Subtitle: The charter boat
 Location: Properties depend on kind
 RecipeLocation: Disenchantment Bay
 Index: The charter boat
@@ -10,7 +9,7 @@ To begin with the title:
 
 	{*}"Disenchantment Bay"
 
-There are many Disenchantment Bays across the world, named by eighteenth-century ships' captains - one in Antarctica, another in Tasmania, for instance. The most famous is probably the one where Lewis and Clark's expedition broke through to the Pacific. But ours is the one in Alaska, named in 1791 by a Spanish navigator who had hoped it might lead to the fabled Northwest Passage, and all of this history is beside the point since the game is set in the present day.
+There are many Disenchantment Bays across the world, named by eighteenth-century ships' captains–one in Antarctica, another in Tasmania, for instance. The most famous is probably the one where Lewis and Clark's expedition broke through to the Pacific. But ours is the one in Alaska, named in 1791 by a Spanish navigator who had hoped it might lead to the fabled Northwest Passage, and all of this history is beside the point since the game is set in the present day.
 
 	{**}The Cabin is a room.  "The front of the small cabin is entirely occupied with navigational instruments, a radar display, and radios for calling back to shore. Along each side runs a bench with faded blue vinyl cushions, which can be lifted to reveal the storage space underneath. A glass case against the wall contains several fishing rods.
 	
@@ -32,6 +31,6 @@ Using "some" rather than "a" or "the" tells Inform that the cushions are to be r
 
 	{**}The bench is enterable.
 
-And now a short script, so that if we type TEST ME, we experiment with the case and bench:
+And now a short script, so that if we type ``test me``, we experiment with the case and bench:
 
 	{**}Test me with "examine case / get rods / open case / get rods / sit on bench / take cushions / get up"

resources/Documentation/Examples/DisenchantmentBay10.txt

@@ -1,5 +1,4 @@
 Example: * Disenchantment Bay 10
-Subtitle: Clothing and possessions
 Location: Possessions and clothing
 RecipeLocation: Disenchantment Bay
 Index: Disenchantment Bay 10. Clothing and possessions
@@ -13,3 +12,4 @@ At this point we can dress both the Captain and the player with some appropriate
 	The player is carrying a backpack and a bottle of water. The player is wearing a pair of sunglasses. The description of the sunglasses is "The light off the water and the ice does get pretty bright sometimes."
 
 (At present the backpack can't be worn, but see the next version.)
+