Adjacency, a rant about documentation

Why is it so hard to find out if two rooms are adjacent when there is a door between them?

I spent at least 30 minutes trying to find something in the Documentation. Eventually I found section 6.14 (in the chapter on Descriptions???) but it still doesn’t answer my question - it just tells me I’ll be stuck at the door again.

I know there’s a handy phrase for dealing with this, but why is it so hard to find?

I don’t recall where I saw this in the docs to be honest, I think I just extrapolated from adjacency.

adjacent-by-doors relates a room (called A) to a room (called B) when A encloses a door (called D) and the other side of D from A is B. The verb to be adjacent-by-doors to implies the adjacent-by-doors relation.

Definition: a room is adjacent-using-doors:
	if it is adjacent-by-doors to the location, yes;
	if it is adjacent to the location, yes;

I’m not sure if that’s an effective way of solving the issue, but hope it helps.

This will work most of the time, but it can fail for rooms that contain more than one door. Whichever door Inform finds first is assigned to “D”, and only the other side of that particular door is checked. One solution is to use route-finding instead: Adjacent-by-doors relates a room (called A) to a room (called B) when the number of moves from A to B, using even locked doors is 1.

Aw, man. I spent a long time trying to use this and getting compiler errors, because I didn’t realize that the comma before “using even locked doors” was necessary. I now see that this is a PEBKAC, because the comma is in section 6.14, but – well, I’m not sure whether that should be highlighted better or if I should just read more carefully.

I see that when you try to put one of these into a text substitution, the compiler error specifically tells you a workaround for using-door-routefinding within a text substitution, which is nice.

Is there a way to do routefinding through open doors only?