@heroiclands/package-build 22.4.5 → 22.4.7

package/docs/commands.md

@@ -1864,7 +1864,8 @@ demo-book: error: the document tree named by `pdf.document` cannot be read
 
 **NAME**
 
-Draw the containment tree, the map from a place, or the whole route graph.
+Draw the containment tree, the map or the chart from a place, or the whole
+route graph.
 
 **SYNOPSIS**
 
@@ -1872,6 +1873,7 @@ Draw the containment tree, the map from a place, or the whole route graph.
 content-build map --tree [--root <shortcode>] [--engine dot|twopi|neato] [--rankdir TB|LR|BT|RL]
                   [--nodesep <inches>] [--ranksep <inches>] [--no-polities]
 content-build map --from <shortcode>.. | --from all
+content-build map --chart <shortcode>.. | --chart all [--horizon <days>]
 content-build map --travel
 content-build map [...] [--scale <factor>] [--base <url>] [--out <dir>]
 ```
@@ -1884,14 +1886,13 @@ index — so a consumer's map draws its dependencies' places beside its own
 and no note is opened except to locate a finding. Everything lands under
 `build/map/`, always the `.dot` beside the `.svg`, so a drawing can be
 re-rendered, diffed or read without the index. GraphViz draws: `dot` (or
-`twopi`, `neato`) for the tree, `neato` for the other two. It is a
-build-time tool of this command alone; when the engine a run needs is not
-installed the command says so, names what to install, and stops. A build
-that asks for maps as one step of a larger job — a site build — writes
-the `.dot` files, emits one warning and skips the renderings rather than
-failing.
+`twopi`, `neato`) for the tree, `neato` for the others. It is a build-time
+tool of this command alone; when the engine a run needs is not installed
+the command says so, names what to install, and stops. A build that asks
+for maps as one step of a larger job — a site build — writes the `.dot`
+files, emits one warning and skips the renderings rather than failing.
 
-The three drawings, any of which may be asked for in one run:
+The four drawings, any of which may be asked for in one run:
 
 **`--tree`** — the author's check. The containment tree from `data.parents`,
 edges running child → parent, clustered by continent — a `region` parented
@@ -1950,6 +1951,39 @@ sailor's chart, a tax survey, partial and from somewhere, whose prose says
 whose it is — and never the survey. The two are two sources of the same
 thing on a place's page.
 
+**`--chart <shortcode>`** — the chart from a place, `chart-<shortcode>.svg`:
+the world-scale drawing chosen by viewpoint rather than projection — the
+sea from a port, the eastern roads from a caravan city. It is the same
+graph from the same place with a larger horizon: the centre pinned, north
+up and east right, the neighbours exactly as `--from` draws them, and
+beyond them the hops chaining on. Hops compose as a running vector sum
+weighted by their days, and a hop is accepted when its bearing lies within
+one octant — 45° either way — of the **running composed direction** at
+that point, not of the previous hop; so a path may bend a little at every
+hop, but never turn back, and a place reached only through a hop that
+turns back is omitted. Where several chains reach one place, the one with
+the fewest total days is drawn. The total is the sum of the hops' days,
+placed on the ring of the smallest marker not less than it. A border
+carries no days: on the first hop it sits on the innermost ring, as on the
+map from a place; beyond the first hop it makes the total unknown, the
+place goes to the rim marked unknown, and the chart states nothing beyond
+it. `all` draws the chart from every place that states or is named in a
+border or a route.
+
+_The horizon._ `--horizon <days>`, a marker of the scale, `360` by default:
+one ring per marker up to and including it, on the same log spacing as the
+map from a place, so a chart to a year's travel is simply a larger page
+with more rings. A place whose total exceeds the horizon is omitted — the
+chart is already the larger view, and there is no "beyond" rim, only the
+unknown one, a log step past the horizon. `--horizon` applies to charts
+alone; the map from a place keeps its horizon of 90 days and its rim.
+
+_The dimming._ The neighbours are drawn full, the second hop as the map
+from a place draws it — grey border and label, pale fill, faint edge —
+and each hop beyond a step fainter, never below half opacity, so the
+farthest place still reads. An edge is dimmed with its far end, and
+labelled with its bearing and days like any other.
+
 **`--travel`** — the whole route graph, `travel.svg`, for the author: one
 undirected edge per pair of places, a border dashed, each route asking
 `neato` for a length on the same log scale as the rings so the god's-eye
@@ -1964,25 +1998,28 @@ page can inline the SVG. Without it the names are plain text.
 
 **OPTIONS**
 
-| Option       | Type    | Default      | Description                                                                                                                                    |
-| ------------ | ------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--tree`     | boolean | `false`      | Draw the containment tree: `tree.svg`, one `tree-<shortcode>.svg` per continent, and the findings.                                             |
-| `--root`     | string  | —            | With `--tree`, draw the subtree beneath this place as `tree-<shortcode>.svg` and report nothing.                                               |
-| `--from`     | string  | —            | Draw the map from this place as `from-<shortcode>.svg`; repeatable, or `all` for every place with a border or a route.                         |
-| `--travel`   | boolean | `false`      | Draw the whole route graph as `travel.svg`.                                                                                                    |
-| `--engine`   | choice  | `dot`        | The tree's layout engine — `dot`, `twopi` (radial, rooted on the world or the `--root`) or `neato`. The other two drawings are always `neato`. |
-| `--rankdir`  | choice  | `TB`         | The tree's rank direction — `TB`, `LR`, `BT` or `RL`; `dot` engine only.                                                                       |
-| `--nodesep`  | number  | by `--scale` | The tree's GraphViz `nodesep`, in inches.                                                                                                      |
-| `--ranksep`  | number  | by engine    | The tree's GraphViz `ranksep`, in inches.                                                                                                      |
-| `--scale`    | number  | `1`          | Multiply every node's width, height, font size and border weight, the legend's included.                                                       |
-| `--polities` | boolean | `true`       | Draw polities beside their regions in the tree. `--no-polities` drops them.                                                                    |
-| `--base`     | string  | —            | The site base this package's pages are served under, ending in a slash; given, every name is a link to its page.                               |
-| `--out`      | string  | `build/map`  | Directory to write into, relative to the working directory.                                                                                    |
+| Option       | Type    | Default      | Description                                                                                                                                |
+| ------------ | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `--tree`     | boolean | `false`      | Draw the containment tree: `tree.svg`, one `tree-<shortcode>.svg` per continent, and the findings.                                         |
+| `--root`     | string  | —            | With `--tree`, draw the subtree beneath this place as `tree-<shortcode>.svg` and report nothing.                                           |
+| `--from`     | string  | —            | Draw the map from this place as `from-<shortcode>.svg`; repeatable, or `all` for every place with a border or a route.                     |
+| `--chart`    | string  | —            | Draw the chart from this place as `chart-<shortcode>.svg` — the map from it at a larger horizon; repeatable, or `all`.                     |
+| `--horizon`  | number  | `360`        | The charts' horizon in days, a marker of the scale: rings are drawn to it, and a place farther than it is left out.                        |
+| `--travel`   | boolean | `false`      | Draw the whole route graph as `travel.svg`.                                                                                                |
+| `--engine`   | choice  | `dot`        | The tree's layout engine — `dot`, `twopi` (radial, rooted on the world or the `--root`) or `neato`. The other drawings are always `neato`. |
+| `--rankdir`  | choice  | `TB`         | The tree's rank direction — `TB`, `LR`, `BT` or `RL`; `dot` engine only.                                                                   |
+| `--nodesep`  | number  | by `--scale` | The tree's GraphViz `nodesep`, in inches.                                                                                                  |
+| `--ranksep`  | number  | by engine    | The tree's GraphViz `ranksep`, in inches.                                                                                                  |
+| `--scale`    | number  | `1`          | Multiply every node's width, height, font size and border weight, the legend's included.                                                   |
+| `--polities` | boolean | `true`       | Draw polities beside their regions in the tree. `--no-polities` drops them.                                                                |
+| `--base`     | string  | —            | The site base this package's pages are served under, ending in a slash; given, every name is a link to its page.                           |
+| `--out`      | string  | `build/map`  | Directory to write into, relative to the working directory.                                                                                |
 
 **EXIT STATUS**
 
-1 when no drawing is asked for, when a `--from` or `--root` names no
-place, when the GraphViz engine a drawing needs is not installed, when a
+1 when no drawing is asked for, when a `--from`, `--chart` or `--root`
+names no place, when `--horizon` is not a marker of the days scale, when
+the GraphViz engine a drawing needs is not installed, when a
 dependency's index cannot be read, when a note the index cannot record is
 met, on any error finding from `--tree` (a place with no parent, a parent
 that does not resolve, a cycle), or on any other thrown error. Otherwise 0
@@ -1999,6 +2036,9 @@ assets/content/Regions/Marches/Lost_Fort.md:9:14: error: place "lostfort" names
 $ content-build map --from dunharargn --base /thalorna/
 […] 394 place(s) → 1 drawing(s) under build/map
 
+$ content-build map --chart takheperurgn --horizon 90
+[…] 394 place(s) → 1 drawing(s) under build/map
+
 $ content-build map --travel
 […] GraphViz's `neato` is not installed, and `content-build map` draws with it; install GraphViz (`brew install graphviz` on macOS, `apt-get install graphviz` on Debian or Ubuntu) and run the command again
 ```

package/docs/configuration.md

@@ -770,6 +770,7 @@ Any other key under `docs.itemFields` is refused:
 | `site.notfound`    | object   | `null`                                      |
 | `site.hugo`        | object   | `{}`                                        |
 | `site.search`      | boolean  | `true`                                      |
+| `site.maps`        | boolean  | `true`                                      |
 
 How much of a package reaches the web at all is **not** here — it is
 [`publish.site`](#publish). `site` is framing: which named pass bundle
@@ -819,7 +820,7 @@ published. A `site.out` is refused by name:
 
 > ``package-build config: `site` must be a mapping.``
 
-> ``package-build config: `site.<key>` is not a recognized option (expected one of: base, assets, description, packages, pass, passOptions, notfound, hugo, search).``
+> ``package-build config: `site.<key>` is not a recognized option (expected one of: base, assets, description, packages, pass, passOptions, notfound, hugo, search, maps).``
 
 `site.assets` is the host every package's imagery is served from, and it is
 the one address in this file that is not this repository's own. A note names
@@ -950,6 +951,24 @@ site:
 
 > ``package-build config: `site.search` must be a boolean.``
 
+`site.maps` is whether every place page carries the map from that place. On
+by default: `content-build site` draws the map `content-build map --from`
+draws — the place's borders and routes, each neighbour at its bearing — for
+every place that states a border or a route or is named in one, lays it beside
+the page as `from-<shortcode>.svg`, and names the file in the page's front
+matter as `map`, which the theme inlines so every place name on it is a link
+to that place's page. A place with no relation carries no map and no key.
+GraphViz draws; when it is not installed the build says so once, as a
+warning, and writes every page as it would without maps — a site never fails
+for want of one. `false` draws nothing and asks nothing of GraphViz.
+
+```yaml
+site:
+  maps: false
+```
+
+> ``package-build config: `site.maps` must be a boolean.``
+
 ### The generated Hugo configuration
 
 `content-build site` writes `build/hugo/hugo.toml` on every run. Every value

package/docs/content-format.md

@@ -2440,6 +2440,23 @@ subType `deity` covers a god's nature, domains, epithets and aspects in prose.
 That frees the name for the territorial sense, which earns it: every affiliation
 subType holds sway somewhere, while the divine sense applies to one.
 
+**`domains` names what the affiliation holds directly**, and nothing beneath
+it. A polity whose `domains` names a region holds the region; the settlements
+within it are the region's, reached through its `contains`, and are not
+repeated here. A house holds its manors and names each; the crown holds the
+realm and names the realm. What lies below a holder is answered by the two
+hierarchies together — `place.parents` for where a place sits, and
+`affiliation.parents` for whom a holder answers to — so a subinfeudated manor
+sits in one region by the first and under a lord of another polity by the
+second, and both pages say so.
+
+The website reads `domains` across the package and every fetched index and
+writes the affiliation's page a `holdings` list — every place its `domains`
+names, each entry `{ title, url, type, subType }`, sorted by `subType` then
+`title`, and absent when `domains` names nothing. Every place it names carries
+the affiliation back in `held_by`. Both are derived; a note that writes one has
+it replaced.
+
 If `sohl` is present, this becomes an `affiliation` item.
 
 | shared source    | → sohl             | → hm3 |
@@ -3087,9 +3104,38 @@ three maps, and none of those maps needs to know it is a keep.
 | `lore`          | `WikiLink[]`                                        | Lore concerning this place — its peoples, its law, its calendar, its history |
 | `parents`       | `WikiLink[]`                                        | Enclosing places within which this place is located                          |
 | `population`    | `number`                                            | Approximate population (precision 2 significant digits)                      |
+| `market`        | `number`                                            | Market class, 1 to 6 — what trade a settlement supports                      |
 | `borders`       | `{ to, bearing }[]`                                 | Places sharing a frontier with this one, and where each lies from here       |
 | `routes`        | `{ to, bearing, mode, days, terrain?, leagues? }[]` | Journeys from this place's centre to another place                           |
 
+#### What a settlement's market supports
+
+`population` states how many people a settlement holds; `market` states what a
+traveller can buy there. Those are different questions — two settlements of
+eight hundred are a different proposition when one holds a weekly market and
+the other a chartered fair with a moneylender — so a note states both, either,
+or neither.
+
+The value is a **class**, not a measurement. The numbers order six steps and do
+nothing else: a `5` is not a market two fifths larger than a `3`, it is a city
+rather than a town. `content-build lint` refuses a value off the scale instead
+of rounding it onto one, so a reader can trust that a number means the same
+thing on every page.
+
+| `market` value | the settlement is | what can be had there                                                                             |
+| -------------- | ----------------- | ------------------------------------------------------------------------------------------------- |
+| `1`            | a hamlet          | no market — what neighbours trade among themselves                                                |
+| `2`            | a village         | a weekly market: staples, a smith, what a household cannot make                                   |
+| `3`            | a town            | a regular market, most common goods, several trades working full time                             |
+| `4`            | a market town     | a chartered fair, goods carried from a week away, a moneylender                                   |
+| `5`            | a city            | anything ordinary, in quantity; foreign goods; a guild structure                                  |
+| `6`            | a great city      | the rare and the imported as a matter of course; banking; the market from which other markets buy |
+
+The key is meaningful on a settlement, and the lint checks no `subType`
+condition — as it checks none for `population`. Which places a fact says
+something about is the author's judgement, and the `data:` container is closed
+per type rather than per subType.
+
 #### Where a place is, in relation to other places
 
 `parents` states what a place is **within**. Two more properties state what
@@ -3187,6 +3233,31 @@ closed set, and each finding is located at the entry that states it.
 | `river`         | boat               |
 | `lake`          | boat               |
 
+#### What lies within a place, and who holds it
+
+`parents` states what a place is within; an affiliation's `domains` states
+what it holds. The website reads both across the package and every fetched
+index and writes each place's page two lists, each entry
+`{ title, url, type, subType }` and each absent when empty:
+
+- `contains` — every place whose `parents` names this one, sorted by
+  `subType` then `title`. A region lists its settlements, sites, structures
+  and features; a settlement lists the structures within it.
+- `held_by` — every affiliation whose `domains` names this one, sorted by
+  `title`.
+
+Both are derived; a note that writes one has it replaced. **`domains` is
+never expanded**: a region held by a polity lists the polity in `held_by`, and
+a settlement within that region lists only the house or order whose `domains`
+names it — its lord's lord is reached through `affiliation.parents`.
+
+**A settlement, a site or a structure is held by someone.** One of those that
+no affiliation's `domains` names — in this package or in a fetched index — is
+a warning from `content-build lint`, `unheld land`, located at the note's
+`type:` line, so a gap in tenure shows while a note is written. A `world`, a
+`region` and a `feature` are exempt: a region is held through its polity's
+`domains`, and a river by nobody.
+
 **A place declares only what is true of ground.** Four properties were removed
 because they were true of something else, and each removal has a home to go to.
 

package/engine/frontmatter-lint.mjs

@@ -1424,6 +1424,8 @@ export function lintNote(
             if (typeof field.check !== "function") continue;
             findings.push(...field.check(note, { index }));
         }
+        // A check the type declares of the whole note, with the same index.
+        if (typeof entry.check === "function") findings.push(...entry.check(note, { index }));
     }
 
     const fields = authoredFields(schema);