A Different Approach to Inform 7 Documentation: A request for comment

Authoring Inform 7
,
3

Interesting project! I haven’t looked at everything yet, but the format and style work quite well, I’d say.

I’m not as big a critic of the official docs as some others are, but it surely can’t hurt to have more learning material with different approaches available, especially since there are conflicting demands… some want the docs to be more like a tutorial, others more like a reference; some like the writing style, others don’t, and so on.

I feel like chapter 3 of the docs is intended to convey the basic worldbuilding information, covering much of the stuff one would need to populate a simple game with rooms, doors, containers, people, food etc.; and the examples below the main text illustrate how to do so, even though they also contain some material from later parts.

In the example for “Up and Down”, you write:

[[When you use north and south you can just specify one of the rooms is north and the other room with know it’s south. With “above” and “below” you have to specify both.]]

That’s not entirely accurate. With this code:

The little clearing is a room.   

The treehouse is above the little clearing.

… the connection will automatically be two-way, as expected, just as with other directions.

A one-way connection can be created in a specific circumstance, cf. 3.3 in the docs:

Finally, note that Inform’s assumptions about two-way directions are only applied to simple sentences. When the source text seems to be saying something complicated, Inform takes it as a precise description of what’s wanted. So, for example, in:

The Attic is above the Parlour.
The Attic is a dark room above the Parlour.

Inform makes guesses about the first sentence, and makes a two-way connection; but it accepts the second sentence more precisely, with just a one-way connection.

I don’t know the full extent of what Inform counts as “complicated”, but this (the addition of “[... is] a room [above ...]”):

The little clearing is a room.   

The treehouse is a room above the little clearing.

… will lead to a one-way connection. (This is the case in your example, which is why you have to specify both ways there.)

The same holds for other directions like north. This:

The little clearing is a room.   

The forest is a room north of the little clearing.

… will also lead to a one-way connection. (In Inform v10; in 6M62, the latter example doesn’t compile.)

Here are some related threads:

5 Likes