What's missing from the General Index?

Authoring Inform 7
1

I’m going through the General Index page (also found in the IDE), trying to clean up and improve organization.

I know people have complained about missing entries in the past, but I never made a TODO list for this. So let’s try it now. What index entries would be useful to add, and where should they be added?

Note that the subject is not reorganizing the Writing With Inform manual. That’s a whole argument I’m not getting into. I’m looking for suggestions like, for example:

§18.28. “Printing a locale paragraph about” explains how to abolish the “describe what’s on scenery supporters” rule. This should be indexed under Supporters.

6 Likes
2

map region (the property) doesn’t have an entry at all.

Most properties mentioned in WI do have entries, but there aren’t sections like, e.g.,

Things
   properties of

which would be pretty nice.

Sadly, I never tried keeping notes when I found omissions either.

Thanks for pursuing this, Andrew.

2 Likes
3

A subject index (like Jim’s TADS periplus) isn’t a bad idea, IMVHO.

(yea, there’s the RB’s thematic index, but isn’t precisely a subject index…)

Best regards from Italy,
dott. Piergiorgio.

4

I’m not making a new index either. :) I am adding entries to the existing index.

5

other things that would be nice; I apologize that some are vague, but I’m brainstorming before needing to get to work…

activities
  list of
    deciding the concealed possessions of something
    deciding the scope of something
    [...]

…as well as rulebooks, list of and rules, list of.

The docs don’t really define “literal” in the programming sense, but I would find it helpful if, on a per kind basis, there were a literal sub-entry with sections regarding how one can/must make such literals, plus a literals entry listing the kinds with the same info. (I still always get adding “action” for action names wrong the first time…)

objects currently has see things and that’s unfortunate, 'cause they’re not the same. (But, of course, sometimes “thing” really means object and the docs don’t always spell that out as clearly as they might.)

properties currently doesn’t have entries discussing defining defaults; it could have, maybe,

properties
  default values
    seldom
    usually
    definition with "with" tucked almost invisibly into one code example in WI 4.2

There’s not an entry for inference and having entries for both the “how the compiler creates the world” and the parsing sense would be good.

condition, naming properties could be a little more clear, like condition, as name for an enumerated kind of value as property

parsing just has see understanding and I think it probably warrants its own entry including sections like related activities and rulebooks.

oops and again don’t have entries. And oops, again, undo would be suitable sub-entries for a parsing entry.

if we have… as in “if we have [actioned] [the particular object]” should have its own entry and its own sub-entry under conditionals, historical.

The listing for topics omits a significant section: 18.33 Activities > Reading a Command.

visibility has a subentry for requirement in defining actions. I’d suggest removing that entry and adding a separate entry for visible thing to not contribute to the conflation of the concepts.

Likewise, it’d be relevant to have touchable thing, carried thing in regard to action specifications; the existing entries for these are for the touchable and carried adjectives; I think those entries would better omit “thing”. thing should get subentries for in action specifications: carried thing, touchable thing, visible thing.

6

assertions deserves list of and sentences as.

sentence possibly warrants an entry with sub-entries for as condition, as assertion, with now

7

Thanks! I will look at all of this.

This is tricky. Most people who are looking up “object” in the index don’t want to know the difference between the Object and Thing kinds; they want to create a brass lamp. It’s bad to have separate “object” and “thing” entries.

Maybe an entry under “thing: as distinct from Object”.

Same goes for “parsing” and “understanding”. There’s no context for parsing as a separate topic that I can think of.

1 Like
8

Object: Also refers to Things. See Thing

Thing: Also refers to Objects. See Object

Note: The difference between Objects and Things are …

9

This doesn’t give the reader any information. It just runs them in a circle.

What would the Object entry refer to? Chapter 4.1? The Thing entry already refers there.

The index doesn’t contain notes.

10

I think this ambiguity in the docs hurts more than helps. People should know, variously, that

  • rooms, regions, directions are as much objects as things are, so testing is an object is very different from is a thing and repeating through the objects is very different from repeating through the things
  • making a subkind of object is very different from making a subkind of thing
  • asserting foo is an object results in foo being a thing
  • thing in action specifications means object
  • [thing] and [any thing] as grammar tokens only match things, but [something] matches all objects in scope

Seems to me like we clarify these points regarding when thing does and doesn’t mean object here a lot, so I think it’s a valuable distinction and it would be helpful for the index to appropriately distinguish them.

OK, how about understanding has a list of related activities and rulebooks ?

A similar list of related activities and rulebooks under looking would be good, too.

2 Likes
11

Just choose one or the other, as appropriate. Maybe even put one as a subtopic.

The note should be placed somewhere else, like in the main text or appendix, where you explain the confusing terminology. Or maybe at the beginning/end of the Index. There’s no reason not to have clarifying note somewhere.

1 Like
12

Do any of the current indices give the same kind of results you get with RESPONSES ALL to list all editable rule responses?

I tried looking today under the Rules tab but couldn’t find anything like that. It seems to come up a lot, easy ways to see all the rule responses and edit them. But from what you said at the beginning, this may be out of scope.

1 Like
13

The compiler-generated Index has this segment:

Bildschirmfoto 2024-04-17 um 09.58.00
Bildschirmfoto 2024-04-17 um 09.58.001284×630 154 KB

Similarly, the details page for the looking action (or any action) has a list of rules that apply, in the order they apply in. I’m not sure how much is to be gained by replicating all that in the general index as well.

(Then again, I rarely use the general index, personally.)

14

An end goal of my docs web remix is to also create an epub (I was at the point of making a reasonable one from the 6M62 docs, but then 10.1 came out…)

I think it’s a reasonable use case to want to read about a programming language while not at a computer and I think it’s a bad thing that so much important information about Inform is unavailable outside of the Project Index.

1 Like
15

Referring to what chapters?

Again, where? I guess this is 9.12 “Actions as conditions”, but this doesn’t actually have an example of “if we have”. An entry under “conditions” makes sense, but not under “if” or “when”.

16

In regard to the former, The Cloak of Darkness example says:

Because we have said the player is wearing the item, Inform infers that it is clothing and can be taken off and put on again at will.

though it doesn’t say inference per se. 3.5 talks about the concept, but doesn’t use the word.

Now that I look, I’m not sure there’s anything about parser inference.

17

I briefly got confused between inference and implications after reading this thread, but that made me check and notice that the latter are also missing from the general index. They could be included both under I and under U (more specifically, under usually). Oh, and I guess under N too (for normally), if you want – it’d just be a clone of the usually index entry. I’m referring specifically to §27.13 here.