diff --git a/inform7/Internal/HTML/main.css b/inform7/Internal/HTML/main.css index bd7bcba16..638817eab 100644 --- a/inform7/Internal/HTML/main.css +++ b/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); diff --git a/resources/Documentation/Examples/BarterBarter.txt b/resources/Documentation/Examples/BarterBarter.txt index 1485f98d1..0898882f5 100644 --- a/resources/Documentation/Examples/BarterBarter.txt +++ b/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. diff --git a/resources/Documentation/Examples/BarterBarterBarter.txt b/resources/Documentation/Examples/BarterBarterBarter.txt index da0d48be2..20014e3e7 100644 --- a/resources/Documentation/Examples/BarterBarterBarter.txt +++ b/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" diff --git a/resources/Documentation/Examples/Bic.txt b/resources/Documentation/Examples/Bic.txt index affbf7561..79bd58e3b 100644 --- a/resources/Documentation/Examples/Bic.txt +++ b/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: diff --git a/resources/Documentation/Examples/GermanChocolate.txt b/resources/Documentation/Examples/GermanChocolate.txt index fdd972704..d2fd92c56 100644 --- a/resources/Documentation/Examples/GermanChocolate.txt +++ b/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." - \ No newline at end of file + diff --git a/resources/Documentation/Examples/Infiltration.txt b/resources/Documentation/Examples/Infiltration.txt index 58c6033ad..740028b64 100644 --- a/resources/Documentation/Examples/Infiltration.txt +++ b/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. diff --git a/resources/Documentation/Examples/IntroductoryLavoriStudies.txt b/resources/Documentation/Examples/IntroductoryLavoriStudies.txt index 2c05fa278..a825a572c 100644 --- a/resources/Documentation/Examples/IntroductoryLavoriStudies.txt +++ b/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. diff --git a/resources/Documentation/Examples/Lanista1.txt b/resources/Documentation/Examples/Lanista1.txt index 8a4638a67..83876ca33 100644 --- a/resources/Documentation/Examples/Lanista1.txt +++ b/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" diff --git a/resources/Documentation/Examples/MoreIdolTalk.txt b/resources/Documentation/Examples/MoreIdolTalk.txt index a6d3e5632..029942a2a 100644 --- a/resources/Documentation/Examples/MoreIdolTalk.txt +++ b/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: diff --git a/resources/Documentation/Examples/NightSky.txt b/resources/Documentation/Examples/NightSky.txt index c4ccbde2f..2b4a79091 100644 --- a/resources/Documentation/Examples/NightSky.txt +++ b/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: diff --git a/resources/Documentation/Examples/Numberless.txt b/resources/Documentation/Examples/Numberless.txt index abeaea3b5..64dc49303 100644 --- a/resources/Documentation/Examples/Numberless.txt +++ b/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. diff --git a/resources/Documentation/Examples/Peek.txt b/resources/Documentation/Examples/Peek.txt index adabe4c3a..bb1b39e44 100644 --- a/resources/Documentation/Examples/Peek.txt +++ b/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: diff --git a/resources/Documentation/Examples/PineRevisited.txt b/resources/Documentation/Examples/PineRevisited.txt index 08817311f..50a8dfe37 100644 --- a/resources/Documentation/Examples/PineRevisited.txt +++ b/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. diff --git a/resources/Documentation/Examples/ProposalRevisited.txt b/resources/Documentation/Examples/ProposalRevisited.txt index b5fa636e4..c2f7c3382 100644 --- a/resources/Documentation/Examples/ProposalRevisited.txt +++ b/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 diff --git a/resources/Documentation/Examples/PureChoice.txt b/resources/Documentation/Examples/PureChoice.txt index 61a2773dc..dd436185c 100644 --- a/resources/Documentation/Examples/PureChoice.txt +++ b/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 - \ No newline at end of file + diff --git a/resources/Documentation/Examples/ShelobsLittleSister.txt b/resources/Documentation/Examples/ShelobsLittleSister.txt index 8837c5c53..c90bbe397 100644 --- a/resources/Documentation/Examples/ShelobsLittleSister.txt +++ b/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. diff --git a/resources/Documentation/Examples/SkeletonFirst.txt b/resources/Documentation/Examples/SkeletonFirst.txt index 4e1a78da6..235cba7da 100644 --- a/resources/Documentation/Examples/SkeletonFirst.txt +++ b/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. diff --git a/resources/Documentation/Examples/SkillsTest.txt b/resources/Documentation/Examples/SkillsTest.txt index c552ba6d1..a3a13b7d5 100644 --- a/resources/Documentation/Examples/SkillsTest.txt +++ b/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 diff --git a/resources/Documentation/Examples/SlightlyWrong.txt b/resources/Documentation/Examples/SlightlyWrong.txt index b52172071..17cd12f20 100644 --- a/resources/Documentation/Examples/SlightlyWrong.txt +++ b/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: diff --git a/resources/Documentation/Examples/SweeneyRevisited.txt b/resources/Documentation/Examples/SweeneyRevisited.txt index b0977041f..72345e76a 100644 --- a/resources/Documentation/Examples/SweeneyRevisited.txt +++ b/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" diff --git a/resources/Documentation/Examples/SwiftPersuasion.txt b/resources/Documentation/Examples/SwiftPersuasion.txt index e0a0bbbed..1e29b932d 100644 --- a/resources/Documentation/Examples/SwiftPersuasion.txt +++ b/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. diff --git a/resources/Documentation/Examples/TestingPureChoice.txt b/resources/Documentation/Examples/TestingPureChoice.txt index 5bd10ee17..5b982f8cd 100644 --- a/resources/Documentation/Examples/TestingPureChoice.txt +++ b/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. diff --git a/resources/Documentation/Examples/TextFoosballCommentated.txt b/resources/Documentation/Examples/TextFoosballCommentated.txt index 1a16a8e0b..32d8af2eb 100644 --- a/resources/Documentation/Examples/TextFoosballCommentated.txt +++ b/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. diff --git a/resources/Documentation/Examples/TheCustomerIsAlwaysRight.txt b/resources/Documentation/Examples/TheCustomerIsAlwaysRight.txt index 069446f70..22668e5ef 100644 --- a/resources/Documentation/Examples/TheCustomerIsAlwaysRight.txt +++ b/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. diff --git a/resources/Documentation/Examples/TheTopOfYourLungs.txt b/resources/Documentation/Examples/TheTopOfYourLungs.txt index 9f6e1d5d6..ef3fca890 100644 --- a/resources/Documentation/Examples/TheTopOfYourLungs.txt +++ b/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. diff --git a/resources/Documentation/Examples/Verbosity1.txt b/resources/Documentation/Examples/Verbosity1.txt index 842a314f5..ca32cbd5e 100644 --- a/resources/Documentation/Examples/Verbosity1.txt +++ b/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. diff --git a/resources/Documentation/Examples/Verbosity2.txt b/resources/Documentation/Examples/Verbosity2.txt index 0d238c800..9a8c4dd51 100644 --- a/resources/Documentation/Examples/Verbosity2.txt +++ b/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. diff --git a/resources/Documentation/Writing with Inform.md b/resources/Documentation/Writing with Inform.md index d6d8053ae..c1917352f 100644 --- a/resources/Documentation/Writing with Inform.md +++ b/resources/Documentation/Writing with Inform.md @@ -190,7 +190,7 @@ Every one of the built-in phrases has a definition somewhere in this book. The f ## Punctuation {PM_UnendingQuote} {PM_UnendingComment} {PM_TooMuchQuotedText} {PM_WordTooLong} {PM_EnigmaticPronoun} {PM_EnigmaticThey} -^^{punctuation} ^^{punctuation: full stop: ending sentences with line breaks} ^^{|.: ending sentences with line breaks}^^^{punctuation: full stop <-- full stop <-- period}^^^{punctuation: full stop <-- punctuation: period}^^^{punctuation: square brackets <-- square brackets} ^^{punctuation: square brackets: comments} ^^{|[ ]: comments} ^^{punctuation: square brackets: text substitutions} ^^{|[ ]: text substitutions} ^^{punctuation: question mark, ending sentences <-- question mark} ^^{(?), ending sentences+sourcepart+} ^^{punctuation: exclamation mark, ending sentences <-- exclamation mark} ^^{(!), ending sentences+sourcepart+} ^^{punctuation: apostrophe, meaning quotation mark <-- apostrophe} ^^{('), meaning (")+sourcepart+}^^^{punctuation: quotation marks <-- quotation marks} ^^{punctuation: quotation marks: defining texts} ^^{|": defining texts} ^^{comments: in source text} ^^{line breaks: produced by sentence-ending punctuation} +^^{punctuation} ^^{punctuation: full stop: ending sentences with line breaks} ^^{|.: ending sentences with line breaks}^^^{punctuation: full stop <-- full stop <-- period}^^^{punctuation: full stop <-- punctuation: period}^^^{punctuation: square brackets <-- square brackets} ^^{punctuation: square brackets: comments} ^^{|[ ]: comments} ^^{punctuation: square brackets: text substitutions} ^^{|[ ]: text substitutions} ^^{punctuation: question mark, ending sentences <-- question mark} ^^{(?), ending sentences+sourcepart+} ^^{punctuation: exclamation mark, ending sentences <-- exclamation mark} ^^{(!), ending sentences+sourcepart+} ^^{punctuation: apostrophe: meaning quotation mark <-- apostrophe} ^^{|': meaning (")+sourcepart+}^^^{punctuation: quotation marks <-- quotation marks} ^^{punctuation: quotation marks: defining texts} ^^{|": defining texts} ^^{comments: in source text} ^^{line breaks: produced by sentence-ending punctuation} The first thing we all learn about punctuation is that full stops finish a sentence. So this is read as two sentences, not one: @@ -478,7 +478,7 @@ Newcomers will probably not need extensions for quite some while, let alone need ## Use options {PM_UONotNumerical} {PM_UnknownUseOption} {OPTIONS} -^^{use options} ^^{use (options...)+assert+} ^^{punctuation: comma: displaying serial comma} ^^^{punctuation: comma <-- comma} ^^{|,: displaying serial comma} ^^{scoring: enabling} ^^{descriptions (displayed): full-length room descriptions / abbreviated room descriptions} ^^{rooms+kind+: descriptions <-- descriptions (displayed): room descriptions} ^^{use options: catalogue: |American dialect} ^^{American dialect+useopt+} ^^{use options: catalogue: |the serial comma} ^^{serial comma+useopt+} ^^{use options: catalogue: |scoring} ^^{scoring+useopt+} ^^{use options: catalogue: |full-length room descriptions} ^^{full-length room descriptions+useopt+} ^^{use options: catalogue: |abbreviated room descriptions} ^^{abbreviated room descriptions+useopt+} ^^{use options: catalogue: |VERBOSE room descriptions} ^^{VERBOSE room descriptions+useopt+} ^^{use options: catalogue: nameless room descriptions} ^^{use options: catalogue: |BRIEF room descriptions} ^^{BRIEF room descriptions+useopt+} ^^{use options: catalogue: |SUPERBRIEF room descriptions} ^^{SUPERBRIEF room descriptions+useopt+} ^^{use options: catalogue: |undo prevention} ^^{undo prevention+useopt+} ^^{>UNDO} +^^{use options} ^^{use (options...)+assert+} ^^{punctuation: comma: displaying serial comma} ^^^{punctuation: comma <-- comma} ^^{|,: displaying serial comma} ^^{scoring: enabling} ^^{descriptions (displayed): full-length room descriptions / abbreviated room descriptions} ^^{rooms+kind+: descriptions <-- descriptions (displayed): room descriptions} ^^{use options: catalogue: |American dialect} ^^{American dialect+useopt+} ^^{use options: catalogue: |the serial comma} ^^{serial comma+useopt+} ^^{use options: catalogue: |scoring} ^^{scoring+useopt+} ^^{use options: catalogue: |full-length room descriptions} ^^{full-length room descriptions+useopt+} ^^{use options: catalogue: |abbreviated room descriptions} ^^{abbreviated room descriptions+useopt+} ^^{use options: catalogue: |VERBOSE room descriptions} ^^{VERBOSE room descriptions+useopt+} ^^{use options: catalogue: |nameless room descriptions} ^^{nameless room descriptions+useopt+} ^^{use options: catalogue: |BRIEF room descriptions} ^^{BRIEF room descriptions+useopt+} ^^{use options: catalogue: |SUPERBRIEF room descriptions} ^^{SUPERBRIEF room descriptions+useopt+} ^^{use options: catalogue: |undo prevention} ^^{undo prevention+useopt+} ^^{>UNDO} One more preliminary. Inform has a small number of optional settings which affect the result of translating the source. The sentence: @@ -1523,8 +1523,8 @@ These are the two ways in which writers size up the world, so Inform provides bo ## Abstract objects and concepts -^^{kinds: catalogue: abstract object} ^^{abstract object+kind+ <-- kinds: catalogue: abstract object} -^^{kinds: catalogue: concept} ^^{concept+kind+ <-- kinds: catalogue: concept} +^^{kinds: catalogue: abstract object} ^^{abstract objects+kind+ <-- kinds: catalogue: abstract object} +^^{kinds: catalogue: concept} ^^{concepts+kind+ <-- kinds: catalogue: concept} The objects seen so far have almost all been physical, in one way or another, and have all belonged to the kinds `thing`, `room`, `region` or `direction`. @@ -2111,7 +2111,7 @@ And this is because `[river sound]` was substituted with the value of the `river ## How Inform reads quoted text -^^{text substitutions: punctuation} ^^{punctuation: square brackets: text substitutions} ^^{|[ ]: text substitutions} ^^{punctuation: quotation marks: defining texts} ^^{|": defining texts} ^^{punctuation: apostrophe, meaning quotation mark} ^^{('), meaning (")+sourcepart+} ^^{punctuation: full stop: ending sentences with line breaks} ^^{|.: ending sentences with line breaks} ^^{punctuation: exclamation mark, ending sentences} ^^{(!), ending sentences+sourcepart+} ^^{punctuation: question mark, ending sentences} ^^{(?), ending sentences+sourcepart+} ^^{line breaks: produced by sentence-ending punctuation} ^^{+to+say "[']"} ^^{+tosay+"[']"} +^^{text substitutions: punctuation} ^^{punctuation: square brackets: text substitutions} ^^{|[ ]: text substitutions} ^^{punctuation: quotation marks: defining texts} ^^{|": defining texts} ^^{punctuation: apostrophe: meaning quotation mark} ^^{|': meaning (")+sourcepart+} ^^{punctuation: full stop: ending sentences with line breaks} ^^{|.: ending sentences with line breaks} ^^{punctuation: exclamation mark, ending sentences} ^^{(!), ending sentences+sourcepart+} ^^{punctuation: question mark, ending sentences} ^^{(?), ending sentences+sourcepart+} ^^{line breaks: produced by sentence-ending punctuation} ^^{+to+say "[']"} ^^{+tosay+"[']"} Text is so fundamental to Inform that the basics had to be covered back in the [The Source Text] chapter, so let's begin this new chapter with a recap. @@ -5381,6 +5381,12 @@ Since scenes are, in the end, only a convenient way to organise rules, and do no ## If again this apparition come... +^^{dialogue: sections <-- (section)+ofsource+} +^^{dialogue beats <-- beats (dialogue) <-- dialogue: sections: beats} +^^{dialogue lines <-- lines (dialogue) <-- dialogue: sections: lines} +^^{dialogue choices <-- choices (dialogue) <-- dialogue: sections: choices} +^^{dialogue beats: |starting beat} ^^{|starting beat} + Some stories are all about exploration: lone travellers going places and discovering things. But other stories are more intimate, and conversational. They involve characters talking to each other about what is happening. And sometimes the talking _is_ what's happening: the story might be a romance, or a political intrigue, or a detective mystery. "Dialogue" is what we'll call the sort of to-and-fro when characters get into a conversation — not necessarily a long talk, but where the story will only work for the player if the speakers seem to be making sense, and not repeating themselves endlessly, or making oblique comments out of nowhere. That means writing something closer to a script than to a rulebook. But that script can still be richly interactive and flexible. In Inform, this is set out in special _dialogue sections_ of the source text. Instead of being set out in sentences and paragraphs like a novel, or a non-fiction book, dialogue sections look like the script for a play or movie: what printers call "playtext". Regular sections cannot contain playtext, while dialogue sections cannot contain anything else. @@ -5537,6 +5543,14 @@ If this section has a moral (other than the inadvisability of killing a king in ## Dialogue sections +^^{dialogue: sections: formatting of} ^^{line breaks: in formatting dialogue} ^^{tabs, for indentation+ofsource+} ^^{indentation+ofsource+} ^^{source text: different in dialogue sections} +^^{dialogue beats} +^^{dialogue beats: |starting beat} ^^{|starting beat} +^^{dialogue lines: speaker of} ^^{speaker (- thing)+actvar+} +^^{dialogue lines: narration} ^^{narration (dialogue lines)} +^^{dialogue choices} +^^{|--: for dialogue choices+sourcepart+} + To recap, then, all dialogue material must appear in special _dialogue sections_ in the source text. A section is a dialogue section if its titling line ends with `(dialogue)`. For example: Section 2 - On the Battlements (dialogue) @@ -5620,6 +5634,26 @@ Here we have two lines of dialogue, and then a divide according to which option ## Dialogue beats and their cues +^^{dialogue: cues <-- dialogue beats: cues for <-- cues (dialogue)} +^^{dialogue beats: as values} ^^{values: dialogue beats as values} +^^{dialogue beats: as scenes} ^^{scenes: defined by dialogue beats} +^^{dialogue beats: conditions} ^^{conditions: for dialogue beats} +^^{dialogue: conversational subjects <-- conversational subject} +^^{dialogue: structure of conversation} +^^{dialogue: cues: named} ^^{this is the (name) beat+cue+} +^^{dialogue: cues: as scenes} ^^{this is the (name) scene+cue+} +^^{dialogue: cues: about a subject} ^^{dialogue beats: about a subject <-- subjects (of dialogue)} ^^{about (subject)+cue+} +^^{dialogue: cues: conditions} ^^{if (a condition)+cue+} ^^{unless (a condition)+cue+} +^^{dialogue: cues: before another beat} ^^{before (a beat)+cue+} +^^{dialogue: cues: after another beat} ^^{after (a beat)+cue+} ^^{immediately after (a beat)+cue+} ^^{later+cue+} ^^{next+cue+} +^^{dialogue: cues: required speakers} ^^{requiring (subject)+cue+} +^^{recurring+cue+} ^^{fully recurring+cue+} ^^{spontaneous+cue+} +^^{dialogue beats: properties} ^^{properties: of dialogue beats} +^^{performed / unperformed (dialogue beat)+prop+} ^^{unperformed / performed (dialogue beat)+prop+} ^^{performed (dialogue beat)+propcat+} ^^{unperformed (dialogue beat)+propcat+} +^^{recurring / non-recurring (dialogue beat)+prop+} ^^{non-recurring / recurring (dialogue beat)+prop+} ^^{recurring (dialogue beat)+propcat+} ^^{non-recurring (dialogue beat)+propcat+} +^^{voluntary / involuntary (dialogue beat)+prop+} ^^{involuntary / voluntary (dialogue beat)+prop+} ^^{voluntary (dialogue beat)+propcat+} ^^{involuntary (dialogue beat)+propcat+} +^^{spontaneous / unspontaneous (dialogue beat)+prop+} ^^{unspontaneous / spontaneous (dialogue beat)+prop+} ^^{spontaneous (dialogue beat)+propcat+} ^^{unspontaneous (dialogue beat)+propcat+} + Each beat begins with a cue paragraph, which must be placed in round brackets. These usually contain a single sentence, but can have more, so long as it all remains a single paragraph. Such sentences must end with full stops, placed inside the brackets. So this is correct: (About the paranormal.) @@ -5813,6 +5847,12 @@ As a special case, a beat can also be described as `fully recurring`. This makes ## When the director is passive +^^{dialogue: director <-- director (dialogue)} +^^{dialogue: director: passive mode} +^^{talking about+action+} +^^{DIALOGUE+testcmd+} ^^{testing commands: >DIALOGUE} +^^{concepts+kind+} + Dialogue is managed during play by a component of Inform called the _director_, which we think of as being like the director of a play. It sometimes has to manage quite a complex situation, so the testing command ``DIALOGUE`` causes the director to explain itself as it goes along; and ``DIALOGUE ALL`` even more so. At any given time the director is either _passive_ or _active_. Passive means that the director performs dialogue as it's asked to do so, but not otherwise. The director is always passive at the start of play and becomes active only if we explicitly ask it to: see [When the director is active]. @@ -5844,6 +5884,10 @@ beat to be performed with a flow marker. (See [Flow Markers] for more.) ## When the director is active +^^{dialogue: director} +^^{dialogue: director: active mode} +^^{dialogue: conversational subjects} + The director remains in passive mode until and unless we say so, using: > phrase: {ph_directoractive} make the dialogue/dialog director active @@ -5904,6 +5948,11 @@ Something to bear in mind is that the director tracks this list all of the time, ## Entrances and exits +^^{dialogue lines: stage directions in} +^^{use options: catalogue: |nameless room descriptions} ^^{nameless room descriptions+useopt+} +^^{(Stage), implicit room+sourcepart+} +^^{on-stage / off-stage (thing)+adj+} ^^{off-stage / on-stage (thing)+adj+} + It's possible to write an entire story made of nothing but dialogue, beginning with a starting beat being performed, and then more beats flowing from that until the story ends. In a story like that, there's no need even to create any rooms. For example: "Not much to say" @@ -5978,6 +6027,19 @@ And if we have joined multiple rooms together into a map, we can even have the a ## Managing dialogue beats +^^{dialogue beats} +^^{dialogue: director: invoking within a specific action} +^^{dialogue beats: as part of an action} +^^{performed / unperformed (dialogue beat)+prop+} ^^{unperformed / performed (dialogue beat)+prop+} ^^{performed (dialogue beat)+propcat+} ^^{unperformed (dialogue beat)+propcat+} +^^{recurring / non-recurring (dialogue beat)+prop+} ^^{non-recurring / recurring (dialogue beat)+prop+} ^^{recurring (dialogue beat)+propcat+} ^^{non-recurring (dialogue beat)+propcat+} +^^{voluntary / involuntary (dialogue beat)+prop+} ^^{involuntary / voluntary (dialogue beat)+prop+} ^^{voluntary (dialogue beat)+propcat+} ^^{involuntary (dialogue beat)+propcat+} +^^{spontaneous / unspontaneous (dialogue beat)+prop+} ^^{unspontaneous / spontaneous (dialogue beat)+prop+} ^^{spontaneous (dialogue beat)+propcat+} ^^{unspontaneous (dialogue beat)+propcat+} +^^{available / unavailable (dialogue beat)+adj+} ^^{unavailable / available (dialogue beat)+adj+} +^^{relevant / irrelevant (dialogue beat)+adj+} ^^{irrelevant / relevant (dialogue beat)+adj+} +^^{being performed (dialogue beat)+adj+} +^^{testing phrases: showme the beat structure of (dialogue beat)+phr+} +^^{dialogue: conversational subjects: making live / dead} + There are many ways to manage dialogue. At one extreme we can put the dialogue director into active mode, and let the automatics do everything, so that conversation happens whenever appropriate in the course of play. Or we can keep it passive, but then run the entire story as one big script of dialogue. If we don't want either of those, though, and want a turn-based story in which there's just occasional dialogue which we will control explicitly as the author, Inform provides an extensive set of phrases to help with that. For example: @@ -6188,6 +6250,12 @@ One way to watch how the list is managed in practice is to add a rule like so, j ## About about +^^{dialogue: cues: about a subject} ^^{dialogue beats: about a subject} ^^{about (subject)+cue+} +^^{dialogue lines: mentioning a subject} +^^{concepts+kind+: in dialogue} +^^{dialogue: conversational subjects: beats about} +^^{dialogue: conversational subjects: lines mentioning} + The whole idea of making the dialogue director "active" is that it enables conversation to develop naturally, in a way which dovetails with everything else that happens in the story. This works best if dialogue beats are marked up with what they are `about`, and if good use is made of marking lines as `mentioning` things. A beat can be `about` any object, but it's mostly sensible to have beats about things — interesting items in the story, or people — or else objects of the `concept` kind, which are used for more abstract ideas. We can freely create those, like so: @@ -6264,6 +6332,33 @@ If a beat is bringing up unexpected new information, which should not be matched ## Dialogue lines +^^{dialogue lines} +^^{dialogue lines: speaker of} ^^{speaker (- thing)+actvar+} +^^{dialogue lines: narration} ^^{narration (dialogue lines)} +^^{dialogue lines: as values} ^^{values: dialogue lines as values} +^^{dialogue lines: matching potential speakers} +^^{interlocutor (- thing)+actvar+} +^^{dialogue lines: mentioning a subject} +^^{dialogue: conversational subjects: lines mentioning} +^^{dialogue lines: conditional} +^^{dialogue lines: properties} +^^{dialogue: director: speaker selection rules} +^^{narrated / unnarrated (dialogue line)+prop+} ^^{unnarrated / narrated (dialogue line)+prop+} ^^{narrated (dialogue line)+propcat+} ^^{unnarrated (dialogue line)+propcat+} +^^{performed / unperformed (dialogue line)+prop+} ^^{unperformed / performed (dialogue line)+prop+} ^^{performed (dialogue line)+propcat+} ^^{unperformed (dialogue line)+propcat+} +^^{recurring / non-recurring (dialogue line)+prop+} ^^{non-recurring / recurring (dialogue line)+prop+} ^^{recurring (dialogue line)+propcat+} ^^{non-recurring (dialogue line)+propcat+} +^^{elaborated / unelaborated (dialogue line)+prop+} ^^{unelaborated / elaborated (dialogue line)+prop+} ^^{elaborated (dialogue line)+propcat+} ^^{unelaborated (dialogue line)+propcat+} +^^{performance notes: named} ^^{this is the (name) line+perfnote+} +^^{performance notes: to an interlocutor} ^^{to (person)+perfnote+} +^^{performance notes: mentioning a subject} ^^{mentioning (subject)+perfnote+} +^^{performance notes: conditions} ^^{if (a condition)+perfnote+} ^^{unless (a condition)+perfnote+} +^^{performance notes: before an action} ^^{before (an action)+perfnote+} +^^{performance notes: after an action} ^^{after (an action)+perfnote+} +^^{performance notes: setting a condition} ^^{now (a condition)+perfnote+} +^^{performance notes: without speaking} ^^{without speaking+perfnote+} +^^{performance notes: performance styles} ^^{performance styles} +^^{|spoken normally} ^^{performance styles: |spoken normally} +^^{|': in elaborated dialogue lines+sourcepart+} ^^{punctuation: apostrophe: in elaborated dialogue lines} + By this point many lines of dialogue have already appeared, some of them with cryptic notes in brackets. It's time now to look at the full range of possibilities. A dialogue line occupies a single complete paragraph, and takes one of these forms: @@ -6412,7 +6507,7 @@ But if we have created a performance style called `spoken with asperity`, then: Marcellus (with asperity): "I've had it with these goddam ghosts." -...would perform it that way. See [Performance styles] for more. +...would perform it that way. See [Managing dialogue lines] for more. ### Properties of lines @@ -6484,6 +6579,21 @@ Henry self-importantly declared: "The greatest TV show of all time is 24." ## Managing dialogue lines +^^{dialogue lines} ^^{dialogue lines: properties} +^^{dialogue lines: textual content of} +^^{performance styles} +^^{|spoken normally} ^^{performance styles: |spoken normally} +^^{narrated / unnarrated (dialogue line)+prop+} ^^{unnarrated / narrated (dialogue line)+prop+} ^^{narrated (dialogue line)+propcat+} ^^{unnarrated (dialogue line)+propcat+} +^^{performed / unperformed (dialogue line)+prop+} ^^{unperformed / performed (dialogue line)+prop+} ^^{performed (dialogue line)+propcat+} ^^{unperformed (dialogue line)+propcat+} +^^{recurring / non-recurring (dialogue line)+prop+} ^^{non-recurring / recurring (dialogue line)+prop+} ^^{recurring (dialogue line)+propcat+} ^^{non-recurring (dialogue line)+propcat+} +^^{elaborated / unelaborated (dialogue line)+prop+} ^^{unelaborated / elaborated (dialogue line)+prop+} ^^{elaborated (dialogue line)+propcat+} ^^{unelaborated (dialogue line)+propcat+} +^^{available / unavailable (dialogue line)+adj+} ^^{unavailable / available (dialogue line)+adj+} +^^{verbal / non-verbal (dialogue line)+adj+} ^^{non-verbal / verbal (dialogue line)+adj+} +^^{performance notes: without speaking} ^^{without speaking+perfnote+} +^^{interlocutor (- thing)+actvar+} +^^{speaker (- thing)+actvar+} +^^{style (- performance style)+actvar+} + This is where we meet two more kinds: `dialogue line` and `performance style`. Each different line of dialogue in the source text is a different `dialogue line` value. That's true even if the texts are the same, as in the famous dialogue between Laurence Olivier (Szell) and Dustin Hoffman (Babe) in _Marathon Man_ (1976): Szell: "Is it safe?" @@ -6571,6 +6681,21 @@ Until the actual moment of performing this, we can't know who exactly will speak ## Decision points +^^{dialogue beats: branches} +^^{dialogue beats: player choices} +^^{|--: for dialogue choices+sourcepart+} +^^{dialogue choices} +^^{dialogue choices: based on actions} +^^{dialogue choices: automatic} +^^{asking the player: for a dialogue choice} ^^{querying the player: for a dialogue choice} +^^{(before), in dialogue choices+sourcepart+} +^^{(after), in dialogue choices+sourcepart+} +^^{(instead of), in dialogue choices+sourcepart+} +^^{(otherwise), in dialogue choices+sourcepart+} +^^{flow markers} ^^{dialogue beats: flow markers <-- dialogue: sections: flow markers} +^^{(<-), flow marker+sourcepart+} +^^{(step through), automatic dialogue choice+sourcepart+} ^^{(step through and stop), automatic dialogue choice+sourcepart+} ^^{(cycle through), automatic dialogue choice+sourcepart+} ^^{(shuffle through), automatic dialogue choice+sourcepart+} ^^{(choose randomly), automatic dialogue choice+sourcepart+} + A _decision point_ is reached when the director is performing a beat and comes to a run of _choices_. The idea is that the player selects one of these choices, and then dialogue continues down whichever branch is called for. ### Textual choices @@ -6738,6 +6863,14 @@ permutation when that completes, and so on ## Dialogue choices +^^{|--: for dialogue choices+sourcepart+} +^^{dialogue choices} +^^{dialogue choices: as values} ^^{values: dialogue choices as values} +^^{dialogue choices: conditional} +^^{dialogue choices: properties} +^^{performed / unperformed (dialogue choice)+prop+} ^^{unperformed / performed (dialogue choice)+prop+} ^^{performed (dialogue choice)+propcat+} ^^{unperformed (dialogue choice)+propcat+} +^^{recurring / non-recurring (dialogue lichoicene)+prop+} ^^{non-recurring / recurring (dialogue choice)+prop+} ^^{recurring (dialogue choice)+propcat+} ^^{non-recurring (dialogue choice)+propcat+} + As we've seen, then, a dialogue choice is written as a paragraph beginning with `--`. Much like dialogue lines, dialogue choices can have optional annotations given to them between round brackets. But if we forget about those, the possible ways to write a choice are: Syntax | What it's for @@ -6807,6 +6940,15 @@ than once in the same play-through? ## Flow markers +^^{flow markers} ^^{dialogue beats: flow markers} +^^{(<-), flow marker+sourcepart+} ^^{(->), flow marker+sourcepart+} +^^{dialogue beats: stopping} +^^{(-> stop), flow marker+sourcepart+ --> stop} +^^{(-> end the story), flow marker+sourcepart+ --> end the story} +^^{(-> perform) beat, flow marker+sourcepart+ --> perform} +^^{(-> another choice), flow marker+sourcepart+ --> another choice} +^^{story structure: ending: in a dialogue beat} ^^{end of story: in a dialogue beat} + Flow markers are written `<-` or `->`, and cause the dialogue director to interrupt its normal performance of a beat. `<-` generally makes a backwards jump in the same beat, while `->` leads out to another beat. Flow markers actually have much in common with choices, and can accept exactly the same bracketed notes as choices have: they can be named and they can be conditional. For example, @@ -6955,6 +7097,14 @@ The reason for the `-> another choice` flow marker is simply that we want two se ## Managing dialogue choices +^^{flow markers: as a sort of dialogue choice} ^^{dialogue beats: flow markers: as a sort of dialogue choice} +^^{dialogue choices: flow markers as choices} +^^{performed / unperformed (dialogue choice)+prop+} ^^{unperformed / performed (dialogue choice)+prop+} ^^{performed (dialogue choice)+propcat+} ^^{unperformed (dialogue choice)+propcat+} +^^{recurring / non-recurring (dialogue lichoicene)+prop+} ^^{non-recurring / recurring (dialogue choice)+prop+} ^^{recurring (dialogue choice)+propcat+} ^^{non-recurring (dialogue choice)+propcat+} +^^{flowing / offered (dialogue choice)+adj+} ^^{offered / flowing (dialogue choice)+adj+} +^^{story-ending (dialogue choice)+adj+ --> story ending} +^^{offering something+descactivity+} ^^{offering+activity+} ^^{dialogue choices: offering+activity+} + As has been mentioned already, each different choice in the source text is a different `dialogue choice` value, and in fact so is each different flow marker: under the surface, a flow marker is really just a special sort of choice. A `dialogue choice` comes with two either-or properties already defined: @@ -7325,7 +7475,7 @@ While this syntax is still allowed for the time being, to keep old source text w ## Otherwise {PM_NonCaseInIf} {PM_MisalignedOtherwise} {PM_MisalignedCase} {PM_MisarrangedOtherwise} {PM_DoubleOtherwise} {PM_OtherwiseIfAfterOtherwise} {PM_CaseValueNonConstant} {PM_CaseValueMismatch} {PM_OtherwiseWithoutIf} {PM_OtherwiseInNonIf} -^^{conditions: with (otherwise/else)+sourcepart+} ^^{+to+if (a condition): with (otherwise/else)+sourcepart+} ^^{Inform 6 equivalent: |switch/case} ^^{(--), separating cases+sourcepart+} ^^{abbreviations: chains of equality tests} +^^{conditions: with (otherwise/else)+sourcepart+} ^^{+to+if (a condition): with (otherwise/else)+sourcepart+} ^^{Inform 6 equivalent: |switch/case} ^^{|--: separating cases+sourcepart+} ^^{abbreviations: chains of equality tests} We often need code which does one thing in one circumstance, and another the rest of the time. We could do this like so: @@ -11845,7 +11995,7 @@ These definitions mentioned blankness several times, and that's the topic to cov ## Blank entries -^^{tables: blank entries <-- blank entries in tables} ^^{(--), as a blank table entry+sourcepart+} +^^{tables: blank entries <-- blank entries in tables} ^^{|--: as a blank table entry+sourcepart+} We are allowed to leave certain entries blank (perhaps to be filled in later, perhaps not) by writing `--` instead of the relevant value: @@ -14194,7 +14344,7 @@ It's best to avoid situations where an item has a locale priority which is highe ## Printing a locale paragraph about {act_plp} -^^{printing a locale paragraph about something+descactivity+} ^^{locale paragraph: printing a locale paragraph about something+activity+} ^^{descriptions (displayed): room contents} ^^{rooms+kind+: printing the room contents} ^^{mentioned / unmentioned (thing)+prop+} ^^{unmentioned / mentioned (thing)+prop+} ^^{mentioned (thing)+propcat+} ^^{unmentioned (thing)+propcat+} ^^{supporters+kind+: that don't list contents in room descriptions} +^^{printing a locale paragraph about something+descactivity+} ^^{printing a locale paragraph about+activity+} ^^{locale paragraph: printing a locale paragraph about something+activity+} ^^{descriptions (displayed): room contents} ^^{rooms+kind+: printing the room contents} ^^{mentioned / unmentioned (thing)+prop+} ^^{unmentioned / mentioned (thing)+prop+} ^^{mentioned (thing)+propcat+} ^^{unmentioned (thing)+propcat+} ^^{supporters+kind+: that don't list contents in room descriptions} **1. When it happens.** See `printing the locale description`. By this point, the locale description process has identified a number of items as candidates to be described, and worked out a priority order. This activity is then called for each candidate in turn, starting with the highest priority items and working downwards. It can either print some text or not, and can either mark the item as `mentioned` or not: if it does, then the item won't appear subsequently in the locale description. If the activity does nothing, the item becomes "nondescript" and falls through into the final ``You can also see...`` paragraph, unless another rule mentions it in the mean time. @@ -14231,7 +14381,11 @@ It's best to avoid situations where an item has a locale priority which is highe ## Performing something {act_performing} -^^{performing something+descactivity+} ^^{dialogue lines: performing something+activity+} +^^{performing something+descactivity+} ^^{performing+activity+} ^^{dialogue lines: performing something+activity+} +^^{interlocutor (- thing)+actvar+} +^^{speaker (- thing)+actvar+} +^^{style (- performance style)+actvar+} +^^{|spoken normally} ^^{performance styles: |spoken normally} **1. When it happens.** Whenever the dialogue director has definitely decided to perform a line of dialogue. The activity shouldn't be used to undo that decision (i.e., by not printing anything): to suppress dialogue, put conditions on it. The activity has three private variables: @@ -14278,7 +14432,7 @@ See [Managing dialogue lines] for more. ## Offering something {act_offering} -^^{offering something+descactivity+} ^^{dialogue choices: offering something+activity+} +^^{offering something+descactivity+} ^^{offering+activity+} ^^{dialogue choices: offering+activity+} **1. When it happens.** Whenever the dialogue director has one or more textual choices to ask the player to select between. This activity applies to a list of dialogue choices, which will never be empty. @@ -18406,7 +18560,7 @@ But that is only the first step. What do we do with the material when we have it ## Bibliographic data {PM_BadEpisode} -^^{bibliographic data <-- metadata <-- publication data} ^^{title+biblio+} ^^{author+biblio+} ^^{headline+biblio+} ^^{release number+biblio+} ^^{genre+biblio+} ^^{story description+biblio+ <-- blurb+biblio+} ^^{punctuation: apostrophe, meaning quotation mark} ^^{('), meaning (")+sourcepart+}^^^{+tosay+"[(unicode character)]" --> unicode character} +^^{bibliographic data <-- metadata <-- publication data} ^^{title+biblio+} ^^{author+biblio+} ^^{headline+biblio+} ^^{release number+biblio+} ^^{genre+biblio+} ^^{story description+biblio+ <-- blurb+biblio+} ^^{punctuation: apostrophe: meaning quotation mark} ^^{|': meaning (")+sourcepart+}^^^{+tosay+"[(unicode character)]" --> unicode character} Almost all printed books have a title page and a so-called "imprint" page, often its verso, which make up a description of the contents. The title page gives the name of the book and of the author, while an imprint page contains a variety of details about the edition, the printing, and so on. An ISBN number is allocated so that, from the number alone, any book seller or cataloguer can identify exactly this work. Sometimes other cataloguing information is added, such as the Library of Congress classification. This set of information is called "bibliographic data", and without it libraries and booksellers would be at a total loss. diff --git a/resources/Documentation/contents.txt b/resources/Documentation/contents.txt index 61aaf6494..e9580bbe4 100644 --- a/resources/Documentation/contents.txt +++ b/resources/Documentation/contents.txt @@ -149,6 +149,10 @@ index notation: ^{headword+descactivity+} = descactivity (under {descriptions (d # index listing.) index notation: ^{headword+token+} = token ("grammar token") (bracketed) (prefix "[") (suffix "]") +# For dialogue cues (on beats) and performance notes (on lines). +index notation: ^{headword+cue+} = cue ("dialogue cue") (bracketed) +index notation: ^{headword+perfnote+} = perfnote ("performance note") (bracketed) + index notation: definition = phrase ("phrase") (bracketed) index notation: if-definition = ifphrase ("if phrase") (bracketed) index notation: say-definition = sayphrase ("say phrase") (bracketed)