Merge pull request #164 from erkyrath/index-tidying-6

Next round of indexing, part 3

inform7/Internal/HTML/main.css

@@ -1851,6 +1851,30 @@ div.generalindex span.indextokenbracketed {
 	font-style: italic;
 }
 
+div.generalindex span.indexcue {
+	color: var(--documentation-index-a-colour);
+    font-family: var(--informcode-fontfamily);
+	font-size: 0.9em;
+}
+
+div.generalindex span.indexcuebracketed {
+	color: var(--documentation-index-b-colour);
+    font-family: var(--informdefault-fontfamily);
+	font-style: italic;
+}
+
+div.generalindex span.indexperfnote {
+	color: var(--documentation-index-a-colour);
+    font-family: var(--informcode-fontfamily);
+	font-size: 0.9em;
+}
+
+div.generalindex span.indexperfnotebracketed {
+	color: var(--documentation-index-b-colour);
+    font-family: var(--informdefault-fontfamily);
+	font-style: italic;
+}
+
 div.generalindex span.indexcommand {
 	color: var(--documentation-index-c-colour);
 	font-family: var(--informcommand-fontfamily);

resources/Documentation/Examples/BarterBarter.txt

@@ -6,6 +6,7 @@ Description: Allowing characters other than the player to give objects to one an
 For: Z-Machine
 
 ^^{giving it to+action+: for other characters}
+^^{characters (people): trading items with}
 
 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.
 

resources/Documentation/Examples/BarterBarterBarter.txt

@@ -4,6 +4,9 @@ RecipeLocation: The Flow of Conversation
 Index: Dialogue, sequences expanding on an existing verb
 Description: Using the dialogue system to create reusable dialogue sequences in which the player can negotiate a complex trade.
 
+^^{characters (people): trading items with}
+^^{flow markers} ^^{dialogue beats: flow markers}
+
 In this expansion of Barter Barter, we use the dialogue system to provide the player with a menu-based way to trade objects with characters, including bargains that depend on characters' particular preferences and the relative value of the items offered.
 
 	{*}"Barter Barter Barter"

resources/Documentation/Examples/Bic.txt

@@ -5,7 +5,7 @@ Index: Checking for missed properties
 Description: Testing to make sure that all objects have been given descriptions.
 For: Z-Machine
 
-^^{Checking for missed properties}
+^^{properties: checking for missing} ^^{descriptions (displayed): checking for missing} ^^{|not for release}
 
 It may occasionally be useful to check whether all objects in our game have a given property. Here we have a `not for release` section that will run at the start of the game and alert us to any objects lacking description:
 

resources/Documentation/Examples/GermanChocolate.txt

@@ -4,6 +4,10 @@ RecipeLocation: Goal-Seeking Characters
 Index: Goal-seeking dialogue
 Description: Allowing a character to doggedly pursue a particular subject of conversation.
 
+^^{dialogue: conversational subjects: characters who search through}
+^^{dialogue: structure of conversation}
+^^{concepts+kind+: in dialogue} ^^{dialogue: conversational subjects: concepts}
+
 Sometimes instead of free-flowing dialogue we may want a character who is able to persistently go after a particular question. Here, we allow goal-seeking so that even if the player changes the topic, the character will keep looking for segues to the important point.
 
 	{*}"German Chocolate"
@@ -94,4 +98,4 @@ Sometimes instead of free-flowing dialogue we may want a character who is able t
 	(About the cocoa industry and economics. Fully recurring.)
 
 	Louisa (without speaking): "Louisa revisits the topic of fair trade chocolate."
-
+

resources/Documentation/Examples/Infiltration.txt

@@ -5,7 +5,7 @@ Index: Room description changes at each of several visits
 Description: A room whose description changes depending on the number of times the player has visited.
 For: Z-Machine
 
-^^{rooms+kind+: descriptions: changing over time}
+^^{rooms+kind+: descriptions: changing over time} ^^{descriptions (displayed): changing over time}
 
 Suppose we have a location that makes the player uncomfortable, and we want its description to change slightly each time they go there, to reflect his increasing unease. We also want the door to that room to show whether they are going there for the first time, or whether this is a repeat visit.
 

resources/Documentation/Examples/IntroductoryLavoriStudies.txt

@@ -4,6 +4,10 @@ RecipeLocation: Helping and Hinting
 Index: Dialogue implementation of a tutorial; magical connection of related objects.
 Description: Teaching the player multiple new commands via an instructor character who comments on the player's progress and reacts to actions taken out of order.
 
+^^{dialogue: teaching the player a tutorial}
+^^{dialogue: structure of conversation}
+^^{scenes: based on dialogue state}
+
 Many games need to teach the player some new verbs that aren't common to other games. In this example, we borrow from the source text of Damnatio Memoriae, a game involving magical links between related objects, and we create an instructor NPC whose job is to teach the player how to use these links.
 
 To do this, we rely heavily on the dialogue system in combination with scenes. Each brief scene asks the player to demonstrate solving a particular task. It moves on when the player has shown the necessary skill, and the instructor also reacts if the player moves too quickly or attempts things that haven't yet been requested. In a real game, we might often want ways for the player to fast-forward through tutorialisation of skills they already understand.

resources/Documentation/Examples/Lanista1.txt

@@ -5,7 +5,7 @@ Index: Lanista 1. Simple Randomised Combat
 Description: Very simple randomised combat in which characters hit one another for a randomised amount of damage.
 For: Z-Machine
 
-^^{combat}
+^^{combat} ^^{characters (people): combat}
 
 	{*}"Lanista, Part One"
 

resources/Documentation/Examples/MoreIdolTalk.txt

@@ -4,6 +4,12 @@ RecipeLocation: Saying Complicated Things
 Description: Modifying the ``TALK ABOUT`` command so that it offers a choice of conversational gambits.
 For: Z-Machine
 
+^^{dialogue: >TALK ABOUT}
+^^{talking about+action+}
+^^{leading beats (- list of dialogue beats)+actvar+} ^^{dialogue beats: |leading beats}
+^^{other beats (- list of dialogue beats)+actvar+} ^^{dialogue beats: |other beats}
+^^{numbers: asking the player for}
+
 This example involves rewriting the `talking about` action, which powers the ``TALK ABOUT`` and ``ASK ABOUT`` commands, to give the player more choice over what is said. To do that, we'll first need to understand how the action normally works. It's an action which first sets up two private-to-it variables:
 
 - `leading beats` is a list of dialogue beats which could in principle be performed and for which the actor is the first speaker;
@@ -65,7 +71,7 @@ This rule only falls through into the existing `first-declared beat rule` if the
 
 - This won't work well if there are beats whose opening line is spoken by the player but `to` an unknown interlocutor who is then mentioned in the course of a text substitution in the line. That's quite unlikely, but still.
 
-- `chosen dialogue number up to X` uses a phrase which we've borrowed from the ordinary dialogue system. It just requires the player to type a number from 1 to `X` inclusive.
+- `a number chosen by the player from 1 to X` uses a phrase which we've borrowed from the ordinary dialogue system. It just requires the player to type a number from 1 to `X` inclusive.
 
 For the sake of testing this:
 

resources/Documentation/Examples/NightSky.txt

@@ -5,7 +5,7 @@ Index: Room description changes after note is read
 Description: A room which changes its description depending on whether an object has been examined.
 For: Z-Machine
 
-^^{rooms+kind+: descriptions: changing over time}
+^^{rooms+kind+: descriptions: changing over time} ^^{descriptions (displayed): changing over time}
 
 Sometimes a nice effect is to change the way things are described depending on the information the player has gained in the course of play. We could for instance write this:
 

resources/Documentation/Examples/Numberless.txt

@@ -5,6 +5,8 @@ Index: Otherwise if demonstrated
 Description: A simple exercise in printing the names of random numbers, comparing the use of "otherwise if...", a switch statement, or a table-based alternative.
 For: Z-Machine
 
+^^{otherwise (a phrase)+phr+}
+
 	{*}"Numberless"
 
 	The Rambling Warren is a room.

resources/Documentation/Examples/Peek.txt

@@ -5,6 +5,8 @@ Index: Examining the contents of memory
 Description: A debugging command for examining the contents of memory.
 For: Z-Machine
 
+^^{units of measure: defining: with other bases} ^^{numbers: hexadecimal and other bases: in units of measure}
+
 ```PEEK``` was an endearingly-named keyword in microcomputer implementations of the BASIC programming language, which let users access memory directly — provided they knew what location to look at. Positions in memory were labelled by _addresses_, from 0 to, usually, something like 65535, although they were often written in hexadecimal instead, and thus ran ```0000``` to ```FFFF```.
 
 We want to distinguish addresses from numbers of bytes — i.e., the position of an area of memory and the size of an area of memory are different concepts, and we want two different kinds for them:

resources/Documentation/Examples/PineRevisited.txt

@@ -4,6 +4,10 @@ RecipeLocation: Characters Following a Script
 Index: Dialogue, with certain topics that need to be covered in a scene
 Description: The Pine 2 example rewritten using the dialogue system, allowing for a scene that ends when critical information has been communicated, regardless of how the conversation flows to that point.
 
+^^{scenes: based on dialogue state}
+^^{dialogue: conversational subjects: tracking used subjects}
+^^{concepts+kind+: in dialogue} ^^{dialogue: conversational subjects: concepts}
+
 A very common scenario in dialogue-heavy games is that we have scenes in which we want the player and other characters to discuss a certain set of topics, regardless of how that happens.
 
 The older "Pine 2" example gives a somewhat laborious implementation of that idea, but it becomes easier to express if we use the dialogue system to let characters move freely between different conversation topics and just set our scene to end when the critical information has been transmitted – however that happens.

resources/Documentation/Examples/ProposalRevisited.txt

@@ -4,6 +4,10 @@ RecipeLocation: Saying Simple Things
 Index: A proposal of marriage using dialogue system
 Description: Mr Spruce proposes again, this time using the dialogue system.
 
+^^{asking the player: for a dialogue choice} ^^{querying the player: for a dialogue choice}
+^^{dialogue choices: based on actions}
+
+
 	{*}"Proposal Revisited"
 
 	Section 1 - The Environs

resources/Documentation/Examples/PureChoice.txt

@@ -4,6 +4,8 @@ RecipeLocation: Alternatives To Standard Parsing
 Index: Branching choices
 Description: Using the dialogue system to write a branching text with no world model to speak of.
 
+^^{dialogue choices: purely choice-based game}
+
 It's quite possible to implement a choice-based story entirely within the dialogue system, so that no commands are ever typed in.
 
 And it's then almost possible to have the source text consist only of a great big dialogue section, but not quite. We still need a room for the player to be in, which we'll call `Stage Set` here. And if there were other actors who spoke in the story, they'd also need to be created as `people` and put in this same room.
@@ -55,4 +57,4 @@ In this example, though, we'll make things look even less like traditional inter
 	Narration: "You have passed through the right door. The narrative has branched, and it will not rejoin; your decision was permanent."
 
 	-> end the story finally
-
+

resources/Documentation/Examples/ShelobsLittleSister.txt

@@ -4,6 +4,9 @@ RecipeLocation: Combat and Death
 Index: Branching choices
 Description: Using the dialogue system to write a combat scene where the player's success depends on their stats.
 
+^^{flow markers} ^^{dialogue beats: flow markers}
+^^{combat: using dialogue beats} ^^{characters (people): combat}
+
 The dialogue system can be used to quickly mock up all sorts of behaviour flows, even ones that don't really have anything to do with conversation.
 
 For instance, if we wanted to mock up some very simple combat, we could express that within a single dialogue beat, which we then re-enter again and again until the combat is concluded. This is marked `fully recurring` to ensure that its options remain available no matter how many times they are encountered.

resources/Documentation/Examples/SkeletonFirst.txt

@@ -4,6 +4,11 @@ RecipeLocation: The Flow of Conversation
 Index: Dialogue inviting the player on a quest
 Description: A sequence of dialogue scenes that introduces the player's life and invites them on a quest.
 
+^^{dialogue: scripted conversations}
+^^{dialogue: structure of conversation}
+^^{story structure: managing complex conversations}
+^^{concepts+kind+: in dialogue} ^^{dialogue: conversational subjects: concepts}
+
 Sometimes we want a scene with a controlled flow of conversation in which the player has to answer questions in a precise order. At other times, we might want on that keeps moving at a steady pace to cover all the key story requirements of that scene, but where the player does have opportunities to stop and look around, change the subject, or even affect which characters are present in the room.
 
 This example shows both of those possibilities. In the first scene, the Sidekick takes the player through a constrained series of questions that we could, in theory, use for character creation. In the second, a Mentor character appears to tell the player about a dangerous quest, but the player has time to choose their own interactions. The third scene consists entirely of the player deciding whether to accept or reject that quest.

resources/Documentation/Examples/SkillsTest.txt

@@ -4,6 +4,8 @@ RecipeLocation: Reactive Characters
 Index: Character commenting on actions
 Description: The judges of Masterchef comment on the player's attempt to cook John Dory.
 
+^^{dialogue: characters commenting on the action}
+
 	{*}"Skills Test" by Previous Me
 
 	Section 1 - The Environs

resources/Documentation/Examples/SlightlyWrong.txt

@@ -5,7 +5,7 @@ Index: Room description changes after first visit
 Description: A room whose description changes slightly after our first visit there.
 For: Z-Machine
 
-^^{rooms+kind+: descriptions: changing over time}
+^^{rooms+kind+: descriptions: changing over time} ^^{descriptions (displayed): changing over time}
 
 A fairly common effect in interactive fiction is a room which is described differently on the first visit than on subsequent visits. We can produce this effect as follows:
 

resources/Documentation/Examples/SweeneyRevisited.txt

@@ -4,6 +4,10 @@ RecipeLocation: Saying Complicated Things
 Index: Conversation topics that evolve over time
 Description: An innocent conversation about the meat products on sale in Bell Yard, London, in 1847.
 
+^^{dialogue: >TALK ABOUT}
+^^{talking about+action+}
+^^{concepts+kind+: in dialogue} ^^{dialogue: conversational subjects: concepts}
+
 Dialogue beats about things are performed in response to the player typing ``TALK ABOUT`` commands, and this short if not sweet example demonstrates that even a very small amount of dialogue can add bustle and character to a location.
 
 	{*}"Sweeney Revisited"

resources/Documentation/Examples/SwiftPersuasion.txt

@@ -4,6 +4,9 @@ RecipeLocation: Obedient Characters
 Index: Dialogue that persuades characters to do things.
 Description: We combine persuasion rules with the dialogue system so that the character who is asked to do a task can require something of the player in turn.
 
+^^{dialogue: director: invoking within a specific action}
+^^{dialogue beats: as part of an action}
+
 Sometimes characters are easily persuaded to do things and sometimes they aren't. But we might want sometimes to place conditions on their cooperation.
 
 In this example, we give the player a menu option choice that they have to resolve — and which in turn will determine whether the other character does as they're asked.

resources/Documentation/Examples/TestingPureChoice.txt

@@ -4,6 +4,10 @@ RecipeLocation: Alternatives To Standard Parsing
 Index: Branching choices
 Description: Modifying the offering activity so that it follows a test script rather than stopping to ask for player input.
 
+^^{dialogue choices: purely choice-based game}
+^^{offering something+descactivity+} ^^{offering+activity+} ^^{dialogue choices: offering+activity+}
+^^{TEST+testcmd+: for pure choice games} ^^{testing commands: >TEST: for pure choice games}
+
 Most Inform examples contain a `Test me with "..."` sentence, giving a sequence of commands which can be automatically typed in for testing purposes.
 
 And that works fine for dialogue-heavy stories too, _provided_ there is a first turn on which the player can type ``TEST ME``. In a story where dialogue takes over the entire narrative, and no regular commands are ever accepted, that's impossible.

resources/Documentation/Examples/TextFoosballCommentated.txt

@@ -4,6 +4,9 @@ RecipeLocation: The Flow of Conversation
 Index: Foosball game
 Description: A foosball game where the other character not only plays against us but reacts to the state of gameplay and riffs on previously-mentioned topics.
 
+^^{dialogue: characters commenting on the action}
+^^{concepts+kind+: in dialogue} ^^{dialogue: conversational subjects: concepts}
+
 In some stories, the player is mostly talking to another character, and their interactions with the environment are largely incidental. In others, the environmental interaction is the main thing – or at least an important priority – but we want the other character to keep up a bit of small talk that feels responsive to world state.
 
 This example explores the latter situation. As in "Text Foosball", we have a fairly randomised foosball game we can play against our opponent Joey; in this case, however, he can use the dialogue system to react to his own mistakes, comment on the state of play generally, riff on prior discussion, or (inevitably) hit up the player for a loan.

resources/Documentation/Examples/TheCustomerIsAlwaysRight.txt

@@ -4,6 +4,8 @@ RecipeLocation: Character emotion
 Index: Dialogue, with responses depending on emotional state
 Description: A character who changes her responses to dialogue gambits depending on her emotional state.
 
+^^{flow markers} ^^{dialogue beats: flow markers}
+
 When it's performing beats, the dialogue system will play the first line of dialogue it can, and it will continue performing lines until it reaches the end of the beat, a decision to take, or a flow marker using `->` or `<-`.
 
 That means that, if we like, we can pack in quite a bit of conditional logic about how a character responds to our input.

resources/Documentation/Examples/TheTopOfYourLungs.txt

@@ -4,6 +4,8 @@ RecipeLocation: Character Emotion
 Index: Speaking in a raised voice
 Description: Adding a ``YELL AT`` verb that selects only yelled dialogue beats.
 
+^^{dialogue beats: which must be yelled}
+
 Some stories may want to offer dialogue interactions beyond the standard ``TALK TO`` or ``TALK ABOUT`` options. Perhaps we want to let the player express emotions or tone of voice; perhaps we want them to use alternate communication styles such as gestures; or perhaps we want to implement higher-level concepts such as ``COMPLIMENT`` or ``INSULT``.
 
 One way to keep our implementation consistent is to apply a property to the relevant dialogue beats so that we can then use an action system to select exclusively for those that match the player's intent. 

resources/Documentation/Examples/Verbosity1.txt

@@ -5,7 +5,7 @@ Index: Verbosity 1. Brief descriptions by default
 Description: Making rooms give brief room descriptions when revisited.
 For: Z-Machine
 
-^^{Verbosity 1. Brief descriptions by default}
+^^{rooms+kind+: descriptions} ^^{use options: catalogue: |abbreviated room descriptions} ^^{abbreviated room descriptions+useopt+} ^^{use options: catalogue: |BRIEF room descriptions} ^^{BRIEF room descriptions+useopt+}
 
 By default, the description of a room is printed every time the player enters a room.
 

resources/Documentation/Examples/Verbosity2.txt

@@ -5,7 +5,7 @@ Index: Verbosity 2. Full-length descriptions mandatory
 Description: Making rooms give full descriptions each time we enter, even if we have visited before, and disallowing player use of ``BRIEF`` and ``SUPERBRIEF``.
 For: Z-Machine
 
-^^{Verbosity 2. Full-length descriptions mandatory}
+^^{(not listed in), for removing rules from rulebooks+sourcepart+} ^^{rules: removing} ^^{descriptions (displayed): full-length room descriptions / abbreviated room descriptions} ^^{use options: catalogue: |full-length room descriptions} ^^{full-length room descriptions+useopt+} ^^{use options: catalogue: |VERBOSE room descriptions} ^^{VERBOSE room descriptions+useopt+}
 
 Suppose that we want the player always to see full room descriptions, even if they try to reset the defaults – perhaps because there is vital information there which they will miss if they turn off full-length room descriptions.