feat: Prosa ist kein Identifier - Link-Taxonomie als Enum, generierte Regionen mit Markern (4.0.0)
Files changed: - .gitea/workflows/ci.yml - AGENTS.md - CHANGES.md - VERSION - instructions/CONTRACT.md - instructions/link-taxonomy.md - instructions/migrations/4.0.0-link-taxonomy.md - instructions/setup-instance.md - kb/CONTRACT.md - kb/CONVENTIONS.md - kb/CONVENTIONS.md.template - kb/comparisons/COLLECTION.md - kb/concepts/COLLECTION.md - kb/entities/COLLECTION.md - kb/sources/COLLECTION.md - tools/CONTRACT.md - tools/README.md - tools/chemenu/blocks.py - tools/chemenu/cli.py - tools/chemenu/commands/cite_cmd.py - tools/chemenu/commands/dist_cmd.py - tools/chemenu/commands/docs_verify.py - tools/chemenu/commands/doctor.py - tools/chemenu/commands/links_cmd.py - tools/chemenu/commands/migrate_cmd.py - tools/chemenu/commands/new_page.py - tools/chemenu/commands/page_ops.py - tools/chemenu/commands/run_budget.py - tools/chemenu/commands/xref.py - tools/chemenu/conventions.py - tools/chemenu/corpus_diff.py - tools/chemenu/frontmatter_io.py - tools/chemenu/kb_collections.py - tools/chemenu/kb_state.py - tools/chemenu/links.py - tools/chemenu/lint_core.py - tools/chemenu/provenance.py - tools/chemenu/sections.py - tools/chemenu/tests/conftest.py - tools/chemenu/tests/test_blocks.py - tools/chemenu/tests/test_cite_cmd.py - tools/chemenu/tests/test_conventions.py - tools/chemenu/tests/test_dist_cmd.py - tools/chemenu/tests/test_doctor.py - tools/chemenu/tests/test_migrate_cmd.py - tools/chemenu/tests/test_new_page.py - tools/chemenu/tests/test_pipeline_l0.py - tools/chemenu/tests/test_types_cmd.py - tools/chemenu/tests/test_xref.py - types/concept.schema.yaml - types/entity.md - types/entity.schema.yaml - types/instruction.schema.yaml - types/type-spec.md - work/link-taxonomy-migration/README.md - work/link-taxonomy-migration/plan.md
This commit is contained in:
+53
-27
@@ -12,9 +12,8 @@ second half is the cut: what is written here is enforced by `tools/wikitool` or
|
||||
how it works, so it is identical everywhere and `dist export` ships it verbatim.
|
||||
|
||||
**What an instance decides for itself is next door, in
|
||||
[kb/CONVENTIONS.md](CONVENTIONS.md)** - the language pages are written in and its three
|
||||
tool-owned section headings, the naming forms, the tone, the relationship-label vocabulary, the
|
||||
confidence rubric. That file binds exactly as this one does; it is simply owned by the instance
|
||||
[kb/CONVENTIONS.md](CONVENTIONS.md)** - the language pages are written in, the headings its two
|
||||
generated regions render under, the naming forms, the tone, the confidence rubric. That file binds exactly as this one does; it is simply owned by the instance
|
||||
rather than by the stack, so the distribution ships only its `.template` and the instance writes
|
||||
the real one. Read both, plus the target collection's `kb/<name>/COLLECTION.md` (also
|
||||
instance-owned), before writing or editing a page.
|
||||
@@ -99,7 +98,8 @@ decision record - is the instance's, in
|
||||
|
||||
- [ ] Carry a clear, descriptive title and a summary near the top
|
||||
- [ ] Use consistent terminology with the rest of the wiki
|
||||
- [ ] Link to every entity and concept it mentions, and be linked to in return
|
||||
- [ ] Link to the entities and concepts it mentions, and declare an edge where the relationship
|
||||
is worth naming - in the direction this page asserts it, not in both
|
||||
- [ ] Cite its hard facts (see [Provenance and citation](#provenance-and-citation))
|
||||
- [ ] Duplicate no existing page
|
||||
- [ ] Appear in the catalog (guaranteed by `wikitool index rebuild`)
|
||||
@@ -141,36 +141,62 @@ instance records - see [kb/CONVENTIONS.md § Language](CONVENTIONS.md#language).
|
||||
evidence *about* a source, not a substitute for it. Quote verbatim in the original language and
|
||||
record the raw file's language in `source_language:`.
|
||||
|
||||
### Section headings
|
||||
### Generated regions
|
||||
|
||||
Three headings are a vocabulary the tool owns rather than prose an author picks: `xref add`
|
||||
writes into Relationships and See Also, and `cite add` owns the trailing Footnotes block. They
|
||||
follow the KB language like everything else, so **the instance names them**, in
|
||||
`kb/CONVENTIONS.md`'s `sections:` frontmatter. `tools/chemenu/conventions.py` reads that
|
||||
declaration and `tools/chemenu/sections.py` is what the rest of the compiler asks - there is no
|
||||
heading text in the compiler itself.
|
||||
Two regions of a page body are **generated**, not authored: the links region `xref` owns and the
|
||||
footnotes region `cite` owns. Each sits between a marker pair:
|
||||
|
||||
Each has aliases the tool still *recognizes* but no longer writes, which is what lets the corpus
|
||||
be translated page by page: a page still carrying `## Relationships` is found and appended to
|
||||
correctly, and `cite sync` leaves an untranslated `## Footnotes` heading alone rather than
|
||||
retitling it. The recognized set is the canonical name, any `section_aliases:` the instance
|
||||
declared, and the names this stack wrote before the declaration existed. Renaming a heading is
|
||||
the translation pass's job, never a side effect of another command. Any *other* heading an
|
||||
author adds is ordinary prose and is translated with the rest.
|
||||
```markdown
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **depends-on:** [[Hermes]]
|
||||
<!-- /wikitool:links -->
|
||||
```
|
||||
|
||||
The marker is what the tool locates the region by, and everything between the markers -
|
||||
**heading included** - is replaced wholesale on the next write. An author never edits inside
|
||||
them; anything left there is overwritten without warning, exactly as in `kb/index.md`. A region
|
||||
with nothing to show is absent rather than empty.
|
||||
|
||||
The heading is therefore a *rendering* value, taken from `kb/CONVENTIONS.md`'s `sections:`. No
|
||||
heading text exists in the compiler, and nothing matches on it: changing the declaration
|
||||
re-renders the words on the next write and cannot split a page.
|
||||
|
||||
That is not how it used to work. The tool located these regions by matching their heading text,
|
||||
which made a translated heading a structural fact - and made the region's *end* a guess. It ran
|
||||
to the next heading, and before that to the end of the file, which silently deleted whatever sat
|
||||
after it on eight pages. Any *other* heading a page carries is ordinary prose.
|
||||
|
||||
## Linking
|
||||
|
||||
Every page links to what it mentions, in both directions. Cross-references are created with
|
||||
`tools/wikitool xref add --a "<A>" --b "<B>" --rel-a "<label>" --rel-b "<label>"`, never by
|
||||
hand-editing the `related:` array or the Relationships/See Also bullets.
|
||||
**An edge is authored in one direction**, on the page that asserts it, and carries a label that
|
||||
is a machine value rather than prose:
|
||||
|
||||
Use a typed relationship label rather than a generic one. The label is free text as far as the
|
||||
tool is concerned - it is written into a `- **label:** [[Title]]` bullet and no code matches on
|
||||
it - so which vocabulary this instance uses is
|
||||
[kb/CONVENTIONS.md § Relationship labels](CONVENTIONS.md#relationship-labels)'s to list.
|
||||
```yaml
|
||||
related:
|
||||
- depends-on: Hermes
|
||||
```
|
||||
|
||||
A page is expected to have at least one inbound link; `wikitool lint` reports orphans.
|
||||
Comparison pages are exempt - they are reached through the catalog.
|
||||
Created with `tools/wikitool xref add --a "<A>" --b "<B>" --rel <label>`, never by hand-editing
|
||||
`related:` or the rendered bullet. Say the sentence before choosing the label - `[A] <label>
|
||||
[B]` - and if it only reads true backwards, the edge belongs on the other page.
|
||||
|
||||
**A reverse edge is a separate decision, not a mirror.** Write one when it independently helps a
|
||||
reader at the other end; do not write one to make the graph symmetric. Navigation does not
|
||||
depend on it either way: `index rebuild` renders the inbound view from the graph, completely and
|
||||
without maintenance.
|
||||
|
||||
Which labels exist is [instructions/link-taxonomy.md](../instructions/link-taxonomy.md), a
|
||||
palette that binds nothing. Which of them a page may *use* is its own collection's `outbound:`
|
||||
block, per destination - the **source** collection decides, because the rules that govern an
|
||||
edge are the rules of the collection asserting it. `xref add` refuses an unauthorised label and
|
||||
`lint` reports one.
|
||||
|
||||
A page is expected to have at least one inbound edge; `wikitool lint` reports orphans.
|
||||
Comparison pages are exempt - they are reached through the catalog. Directional edges mean more
|
||||
pages qualify than under the old mirrored model, and that is the check measuring reachability
|
||||
rather than measuring whether `xref` ran.
|
||||
|
||||
Renaming a page, deleting one, or dropping a single reference are tool operations with their
|
||||
own procedure: see [instructions/page-lifecycle.md](../instructions/page-lifecycle.md).
|
||||
|
||||
Reference in New Issue
Block a user