I drew up this summary of what’s in the Index (under Actions->Tokens) and what’s in Chapter 17, which I find helpful as a reference. The hotlinks in the Index page are very useful for browsing.
An action needs two things to anchor it fully in the game world:
(i) (Photographing) is an action applying to nothing/(one/two) (visible/touchable/carried/–) (thing(s)/value(s)) [and one…] [and requiring light]. → a framework for how the action works in the game world
NB 1 ‘thing’ here means object, so includes rooms, regions and directions.
NB 2 confusingly, ‘visible’ here means ‘within the universe’ not the more usual ‘visible to the actor’. So it includes for example the compass directions and objects out-of-play- although when parsing the player’s commands, by default objects not visible in the usual sense will generally be excluded from consideration by grammar lines (see below), usually with the retort ‘You can’t see any such thing.’. Without specifying ‘visible/carried’, ‘touchable’ is the default. ‘carried’ is a more restrictive form of ‘touchable’ and will ordinarily invoke a preliminary attempt to take an object not already held by the actor, announced by (first taking the …)
NB3 the ‘touchable’ criterion is applied only to things, not other objects such as rooms or regions, so perversely, in the case for example of a room, a ‘touchable thing’ in an action definition is sometimes allowed to be neither a thing nor touchable.
(ii) Understand “photograph [someone]” as photographing. → grammar line(s) to allow the parser to recognise the action in what is typed by the player
NB4 It is possible to create ‘untypable’ actions with no corresponding ‘Understand…’ lines, which are thus not directly accessible to the player via typed commands and the parser but can nevertheless be invoked by Inform code such as ‘Instead of taking the rose, try plucking the rose’
NB5 Since scope is only something of concern to grammar tokens and hence the parser- as are any other considerations imposed by tokens and grammar lines- actions invoked directly by Inform code need only comply with the basic framework outlined in (i). Thus we can legitimately write ‘try talking to the location’ even though rooms are ordinarily neither in scope nor persons to be talked to.
built-in tokens:
[something] → an object in scope for the actor § §§
[thing] → a thing in scope for the actor
[things] → a list of one or more objects in scope for the actor
[other things] → a list of one or more objects in scope for the actor which are not the other object mentioned (e.g. a container)
[things inside] → a list of one or more objects in or on the other object mentioned (e.g. a supporter/container) and in scope for the actor
[something preferably held] → as with [something], but choose a held object over others with same name, try implied take if present but not held
[things preferably held] → as with [things], but choose a held object over others with same name, try implied take if present but not held
[somebody] / [someone] → synonyms == a person §§§§§ in scope for the actor => the [second] noun (rather than ‘the person understood’)
[text] → an unparsed sequence of words => a snippet called ‘the topic understood’ §§§
[a time period] → a period of time §§§§ => a time called ‘the time understood’
[description of objects/values] → matching any description of objects ([open door]) in scope for the actor, or of values ([even number])
→ [description of directions] references directions. NB directions are ‘visible’ (in the sense of ‘in the universe’) but not ‘touchable’ (see above)
→ prefixing ‘any’ e.g. [any open door] removes the restriction that an object must be in scope for the actor
→ [any thing] will allow any thing, in or out of the game world == [anything]; similarly [anybody], [anyone], [any object]
→ [any (description of rooms/regions)] thus allows reference to rooms or regions, not otherwise mentionable in typed commands unless deliberately placed in scope
→ [anywhere] == [any room]
→ the Index indicates which built-in values have a corresponding Understand token
=> for values, a value called ‘the (kind) understood’
=> for objects, the [second] noun
§ ‘in scope for’ is a subtly different concept to ‘visible to’. Formally, an object is in scope for an actor if it can be referred to by the parser when creating an action for that actor from a typed command. Although most things an actor can see will be in scope and vice versa, there are exceptions- a common example being the actor’s possessions when in darkness, which are invisible but in scope.
See here and here.
§§ generally, grammar tokens refer to objects and are not restricted to things. Exceptions are [thing], [any thing] and (very confusingly) [any something], which are restricted to things. [things] also refers to objects rather than things! NB [object] is not itself a built-in token, although (again confusingly) [any object] and [objects] are…
§§§ this is something of an exception, for historical reasons, to the general ability to refer to a successfully-parsed grammar token as ‘the (kind) understood’, which here would otherwise be ‘the snippet understood’. The number representing ‘the topic understood’ snippet can be found in the I6 variable
parsed_number. Using ‘the noun’ and ‘the second noun’ to refer to the first and second object parsed are also exceptions. But we say for example ‘the number understood’ or ‘the time understood’ or ‘the colour understood’ for values. There is also ‘the person asked’ for constructions such as ‘Bob, open the box’.
§§§§ this special token is provided because [a time], which follows the general [description of values] pattern, matches only specific times of day but does not match ‘21 minutes’ for example, even though this is also of kind time. However, the parsed value is still referred to as ‘the time understood’ rather than ‘the time period’ understood.
§§§§§ or more accurately, a person or an object which can be spoken to, i.e. one that has the Inform 6 attribute ‘talkable’. This distinction is not usually utilised in Inform 7, which does not ordinarily create ‘talkable’ objects that are not persons. The grammar token [person] is formally restricted to persons.