Relates

Stable — Stable features are ones that have earned their place in the core prose language.

universe ClockworkVillage {
  describe { ... }
}

dimension place { describe { ... } }
dimension thing { describe { ... } }

relationship isNextTo { describe { ... } }
relationship sitsOn and isSatOnBy { describe { ... } }

concept Villager {
  describe { ... }

  relationships {
    sitsOn { Bench }
  }
}

place Well {
  describe { ... }

  thing WellRope {
    describe { ... }
  }
}

thing Water {
  describe {
    Water is gathered from the well by the villagers.
  }
}

relates Well and Water {
  describe {
    The well is the most convenient source of water in the village, so
    many villagers gather there each day in the hope of running into
    someone.
  }
}

place Pond {
  describe { ... }
}

place Bench {
  describe { ... }

  relationships {
    isNextTo { Pond }
  }
}

What it is

A pairing that is worth describing on its own.

A relationships block puts an edge on one thing and looks outward from it. A relates block stands between two things and describes the pair itself. The paragraph above belongs to neither the well nor the water — it belongs to the space between them, and there was nowhere else to put it.

That is the whole reason relates exists. Some meaning lives in a pair rather than in either member.

Meaning about one connection is different. Why the villager sits on the bench is about that connection, so it belongs on the connection itself, in the block after its target (Relationships, under Each edge, separately). A relates block is for what two things mean together, whether or not anything connects them.

Where it can live

At file scope, beside the things it pairs. Either side may be a concept or a dimension.

A relates block holds a describe and a relationships block. It does not hold declarations — nothing new is named inside it, because it is a statement about two things that already exist.

How names find it

Both names have to be in reach from where the block is written, the same as any other reference.

A relates block may also carry a relationships block, and the words in it are the ones already declared elsewhere. It does not name new ones. If a pair needs a word that does not exist yet, declare the relationship first and then use it here.

Every target has to be one of the two paired names. That is how the block says which way a connection runs without ever writing a subject: naming one endpoint as the target leaves the other one to be it.

In the pairing of Well and Water above, a connection whose target is Water has Well as its subject, and one whose target is Well has Water. Which name you wrote first makes no difference — relates Water and Well binds exactly the same way.

A target that is neither name is SP026. Nothing would be left to be the subject, so the connection would have no direction at all. A fact about only one of the two belongs in that thing's own relationships block, where the subject is whatever contains it.

How it breaks

• SP005 DisallowedKindError — Some blocks only allow certain kinds of declaration.
• SP007 TargetNotFoundError — A name used as a target could not be found.
• SP015 RelationshipNotFoundError — That relationship word is not in reach.
• SP026 TargetNotInPairError — A relates block describes a pairing, so every connection written inside it has to be about the two things being paired.

Decided in

• ADR006 DimensionsInRelationships — Dimension relationship endpoints. Accepted.
• ADR007 RelatesEndpointDimensionPairs — Relates endpoint dimension pairs. Accepted.
• ADR012 FileScopeUniverse — File-scope universe. Accepted.
• ADR017 LinksInDescribe — Links in describe. Accepted.
• ADR023 ErrorNameCorrections — Error name corrections. Accepted.
• ADR024 RelatesTargetsInPair — Relates targets must be in the pair. Accepted.
• ADR029 EdgeBlocks — Edge blocks. Accepted.