Merge pull request #144 from erkyrath/index-tidy-2

Improvements to General Index (part 1)

inbuild/supervisor-module/Chapter 7/General Index.w

@@ -590,6 +590,7 @@ int Indexes::sort_comparison(const void *ent1, const void *ent2) {
 	for (int i=0; i<NL; i++) {
 		index_lemma *il = lemma_list[i];
 		if ((just_examples) && (il->example_index_status == 0)) continue;
+		if ((!just_examples) && (il->example_index_status == 2)) continue;
 		inchar32_t incipit = Str::get_first_char(il->sorting_key);
 		if (Characters::isalpha(incipit)) incipit = Characters::toupper(incipit);
 		else incipit = '#';

resources/Documentation/Examples/3AM.txt

@@ -5,6 +5,8 @@ Index: SHAKE command
 Description: A shake command which agitates soda and makes items thump around in boxes.
 For: Z-Machine
 
+^^{SHAKE command}
+
 	{*}"3 AM"
 
 	Understand "shake [something preferably held]" as shaking.

resources/Documentation/Examples/AARPGnosis.txt

@@ -5,6 +5,8 @@ Index: Encyclopedia set
 Description: An Encyclopedia set which treats volumes in the same place as a single object, but can also be split up.
 For: Z-Machine
 
+^^{Encyclopedia set}
+
 Suppose we have a complete Encyclopedia in our game. The player is allowed to pick up the whole set (there must not be too many volumes), but also to do things with individual volumes, and indeed to scatter these volumes all over the place. Putting a volume back in the same place as the rest of the Encyclopedia should, however, restore it to the collective. We will start out by defining general rules for collectives like this:
 
 	{*}"AARP-Gnosis"

resources/Documentation/Examples/ADayForFreshSushi.txt

@@ -5,6 +5,8 @@ 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
 
+^^{characters (people): reacting to the player's actions}
+
 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:

resources/Documentation/Examples/AE.txt

@@ -5,6 +5,8 @@ Index: Region off-limits to a player without VIP pass
 Description: Using regions to block access to an entire area when the player does not carry a pass, regardless of which entrance they use.
 For: Z-Machine
 
+^^{Region off-limits to a player without VIP pass}
+
 Rules about going to regions make it easy to exclude the player from a large portion of the map, even if there are many connecting paths to the region. For instance, in this story it would be annoying to have to write a rule about all four exits by which the player could reach the film set area:
 
 	{*}"A&E"

resources/Documentation/Examples/AHaughtySpirit.txt

@@ -5,6 +5,8 @@ Index: Windows in high places
 Description: Windows overlooking lower spaces which will prevent the player from climbing through if the lower space is too far below.
 For: Z-Machine
 
+^^{Windows in high places}
+
 Suppose we have a game in which the player can climb through windows which overlook rooms below. We want them to be allowed to climb out windows to reach a room on the same level or at most one level lower than the one they're on; otherwise, they should get a refusal, saying that they would break their neck.
 
 To figure out the height distance between the start room and the destination room, we might have a repeat loop look at all the directions one has to follow along the "best route" path between the two rooms, and record any ups and downs; then subtract the number of "up" steps from the number of "down" steps, and report what remains.

resources/Documentation/Examples/AHumbleWaysideFlower.txt

@@ -5,6 +5,8 @@ Index: People introduced by relative
 Description: Relations track the relationships between one character and another. Whenever the player meets a relative of someone they already know, they receive a brief introduction.
 For: Z-Machine
 
+^^{characters (people): tracking their relationships}
+
 First we define the relationships we choose to acknowledge:
 
 	{*}"A Humble Wayside Flower"

resources/Documentation/Examples/APointForNeverSavingTheGame.txt

@@ -5,6 +5,8 @@ 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.
 For: Untestable
 
+^^{saving the game: reward for never saving}
+
 Here is one way to score this point with Inform:
 
 	Check saving the game for the first time: decrement the score.

resources/Documentation/Examples/AViewOfGreenHills.txt

@@ -5,6 +5,8 @@ Index: LOOK [direction] command
 Description: A ``LOOK`` [direction] command which allows the player to see descriptions of the nearby landscape.
 For: Z-Machine
 
+^^{looking+action+: in a direction}
+
 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"

resources/Documentation/Examples/AboutInformsRegularExpressionSupport.txt

@@ -5,6 +5,8 @@ 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
 
+^^{regular expressions}
+
 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:

resources/Documentation/Examples/AboutTheExamples.txt

@@ -5,6 +5,8 @@ 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
 
+^^{examples}
+
 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 **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.

resources/Documentation/Examples/AccessAllAreas.txt

@@ -5,6 +5,8 @@ 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
 
+^^{The Pointy Hat of Liminal Transgression}
+
 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:

resources/Documentation/Examples/Actaeon.txt

@@ -5,6 +5,8 @@ Index: FOLLOW command
 Description: A ``FOLLOW`` command allowing the player to pursue a person who has just left the room.
 For: Z-Machine
 
+^^{>FOLLOW}
+
 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.
 
 	{*}"Actaeon"

resources/Documentation/Examples/ActorsStudio.txt

@@ -5,6 +5,8 @@ Index: Video camera that records all actions
 Description: A video camera that records actions performed in its presence, and plays them back with time-stamps.
 For: Z-Machine
 
+^^{Video camera that records all actions}
+
 Here we construct a video camera to track and play back actions:
 
 	{*}"The Actor's Studio"

resources/Documentation/Examples/Aftershock.txt

@@ -5,6 +5,8 @@ Index: Radios and other devices active when switched on
 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
 
+^^{Radios and other devices active when switched on}
+
 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:

resources/Documentation/Examples/AgeOfSteam.txt

@@ -5,6 +5,8 @@ Index: Scene which starts and finishes
 Description: The railway-station examples so far put together into a short game called "Age of Steam".
 For: Z-Machine
 
+^^{Scene which starts and finishes}
+
 The following source is very short and simple, yet it already feels surprisingly interesting in play, because something is going on which the player does not control but must observe. The single scene both starts and finishes.
 
 	{*}"Age of Steam"

resources/Documentation/Examples/Ahem.txt

@@ -5,6 +5,8 @@ Index: Phrase to repeat a rule
 Description: Writing a phrase, with several variant forms, whose function is to follow a rule several times.
 For: Z-Machine
 
+^^{Phrase to repeat a rule}
+
 As we see in the example here, it is possible to use slashed variations in more than one place in a phrase, and to offer a number of separate forms. The main rule of thumb to remember is that value inputs for the phrase should always be separated by some text; so
 
 	To do/follow (chosen rule - a rule) exactly/precisely/just/-- (N - a number) time/times:

resources/Documentation/Examples/AirConditioningIsStandard.txt

@@ -5,6 +5,8 @@ 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 randomised NPC interactions with objects or with each other.
 For: Z-Machine
 
+^^{Paragraphs of flexible descriptions}
+
 	{*}"Air Conditioning is Standard"
 
 	Section 1 - The Garage

resources/Documentation/Examples/Alias-G.txt

@@ -5,6 +5,8 @@ Index: Telephones with standard American-length phone numbers
 Description: A telephone with phone numbers of the standard American seven-digit length.
 For: Glulx
 
+^^{Telephones with standard American-length phone numbers}
+
 Seven-digit telephone numbers are too long for Inform to handle when compiling to the Z-Machine, but they will work under Glulx. To have this example succeed, make sure that you have selected the Glulx option in your settings menu.
 
 	{*}"Alias"

resources/Documentation/Examples/AlienInvasionPart23-G.txt

@@ -5,6 +5,8 @@ Index: Preferences file loaded on replaying
 Description: Keeping a preference file that could be loaded by any game in a series.
 For: Glulx
 
+^^{Preferences file loaded on replaying}
+
 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:
 
 	{*}"Alien Invasion Part 23"

resources/Documentation/Examples/AllRoadsLeadToMars.txt

@@ -5,6 +5,8 @@ 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
 
+^^{connections between rooms: changing}
+
 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"

resources/Documentation/Examples/AlpacaFarm.txt

@@ -5,6 +5,8 @@ Index: USE action which divines rational behaviour for a wide range of possible
 Description: A generic ``USE`` action which behaves sensibly with a range of different objects.
 For: Z-Machine
 
+^^{USE action which divines rational behaviour for a wide range of possible nouns}
+
 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.
 
 	{*}"Alpaca Farm"

resources/Documentation/Examples/Alpha.txt

@@ -5,6 +5,8 @@ Index: Testing command
 Description: Creating a beta-testing command that matches any line starting with punctuation.
 For: Z-Machine
 
+^^{Testing command}
+
 Sometimes we want to let testers of a game insert their own comments during a transcript, without those comments wasting turns of the game or producing lengthy or inappropriate parser errors. Many testers have a habit of prefacing comments with a punctuation mark, so let's say that we'd like to catch any command that starts with any punctuation at all:
 
 	{*}"Alpha"

resources/Documentation/Examples/AmericaStandsTall.txt

@@ -5,6 +5,8 @@ Index: Feet and inches
 Description: Describing height in feet and inches.
 For: Z-Machine
 
+^^{Feet and inches}
+
 	{*}"America Stands Tall"
 
 	The Oval Office is a room. Josh and Toby are men in the Oval. A height is a kind of value. 5 foot 11 specifies a height. A person has a height. Josh is 5 foot 8. Toby is 5 foot 10.

resources/Documentation/Examples/Anchorite.txt

@@ -5,6 +5,8 @@ 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.
 For: Z-Machine
 
+^^{>GET: GET DOWN and DOWN understood as EXIT}
+
 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"

resources/Documentation/Examples/AnnoyotronJr.txt

@@ -5,6 +5,8 @@ Index: Child who asks if we're there yet
 Description: A child who after a certain period in the car starts asking annoying questions.
 For: Z-Machine
 
+^^{characters (people): acting spontaneously: asking questions} ^^{actions: spontaneous by other people}
+
 	{*}"Annoyotron Jr"
 
 	The Minivan is a room. The Open Road is outside from the Minivan. Pete is a man in the Minivan. "Pete [if the player has been in the Minivan for 3 turns]is starting to look bored[otherwise]is playing with his travel activity book[end if]."

resources/Documentation/Examples/AntSensitiveSunglasses.txt

@@ -5,6 +5,8 @@ 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
 
+^^{Varying room description text}
+
 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:

resources/Documentation/Examples/Anteaters.txt

@@ -5,6 +5,8 @@ Index: Device to remember and play back actions
 Description: The player carries a gizmo that is able to record actions performed by the player, then force them to repeat those actions when the gizmo is dropped. This includes storing actions that apply to topics, as in ``LOOK UP ANTEATER COLONIES IN THE GUIDE``.
 For: Z-Machine
 
+^^{Device to remember and play back actions}
+
 	{*}"Anteaters"
 
 	A book is a kind of thing. Understand "book" as a book. A book has a table name called the contents.

resources/Documentation/Examples/Apples.txt

@@ -5,6 +5,8 @@ Index: Disambiguation question giving items more explicit names
 Description: Prompting the player on how to disambiguate otherwise similar objects.
 For: Z-Machine
 
+^^{Disambiguation question giving items more explicit names}
+
 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 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:

resources/Documentation/Examples/AsTheCrowFliesToIffleyLock-G.txt

@@ -5,6 +5,8 @@ Index: Grid references
 Description: Calculated walking distances based on grid references at start and end of a walk.
 For: Glulx
 
+^^{Grid references}
+
 The Ordnance Survey National Grid reference system (OSGB) was developed in 1936 for the great retriangulation, which led to the building of many concrete pillars on British hilltops and to today's maps. The full range of values is enormous, since OSGB can specify any point in the British Isles to an accuracy of 1m. Fortunately, we only want to use positions in the town of Oxford, which sits fully inside a modest rectangular portion of square `SP`. So:
 
 	{*}"As The Crow Flies To Iffley Lock"

resources/Documentation/Examples/Aspect.txt

@@ -5,6 +5,8 @@ Index: Understanding units as part of the name of a thing
 Description: Understanding aspect ratios (a unit) in the names of televisions.
 For: Z-Machine
 
+^^{Understanding units as part of the name of a thing}
+
 Named properties are not the only kind that Inform is able to understand referring to an object. We can also use unit and number properties to distinguish things from one another, as here, where televisions have aspect ratios:
 
 	{*}"Aspect"

resources/Documentation/Examples/BadHairDay.txt

@@ -5,6 +5,8 @@ Index: Examining the player
 Description: Change the player's appearance in response to ``EXAMINE ME``.
 For: Z-Machine
 
+^^{examining+action+: the player}
+
 	{*}"Bad Hair Day"
 
 	The Foyer is a room. "A mirror hangs over the table, tempting you to check your appearance before going in with all the others."

resources/Documentation/Examples/Baedeker.txt

@@ -5,6 +5,8 @@ Index: Producing an EPS floorplan
 Description: Creating a floorplan of the cathedral using the locations from previous examples.
 For: Z-Machine
 
+^^{Producing an EPS floorplan}
+
 If our map is largely or entirely set inside a single building, we might want to produce something that resembles a floorplan. It's possible to do this with a little tweaking, like so:
 
 	{*}"Baedeker"

resources/Documentation/Examples/Ballpark.txt

@@ -5,6 +5,8 @@ Index: Saying a number in round numbers
 Description: A new `to say` definition which allows the author to say `"[a number in round numbers]"` and get verbal descriptions like ``a couple of`` or ``a few`` as a result.
 For: Z-Machine
 
+^^{Saying a number in round numbers}
+
 Sometimes it is more sensible to describe numbers roughly than in exact terms. For instance, we might want to have our player perceive ``many people`` rather than ``forty-two people`` on entering a room. To achieve this, we might write our own `to say` phrase.
 
 	{*}"Ballpark"