Link example documents to their elements #4

Merged

moof merged 0 commits from example-links into main

2026-10-21 01:19:29 +00:00

moof commented

2026-10-21 00:22:45 +00:00

(Migrated from code.moof.space)

Requested by Moof · project thread

Adds --examples DIR. Every .xml file under the directory gets a page under examples/ with its element names linked to their declarations, and every global element page gets an Examples section listing the examples that use it, each linked to the line of its first occurrence (with an occurrence count). The index gets an "All N examples" tree, like the source-file one.

How elements are matched

Each element is resolved against its parent's content model (base types, groups, compositors, substitution groups, xsi:type), so a local element links to the row that declares it: <Name> inside a <Line> goes to line.html#d213-341, not to some other Name. When the content model doesn't explain an element (wildcards, unknown parents, invalid examples) it falls back to a global element with the same name. On the 290 NeTEx examples against NeTEx_publication.xsd, 856,807 of 857,797 start tags get a link.

Size

Example pages store the document as plain text (only & and < escaped) plus a compact list of link targets per start tag, and site.js highlights it and adds the links in the browser. Line numbers use the CSS counter from #3. For NeTEx, the examples are 53 MB of XML and the examples/ output is 64 MB; rendering them server-side with a link per tag would have roughly doubled that. The largest example (5 MB, 139k lines) renders in about 7 s in headless Chromium; lines are laid out in 200-line chunks with content-visibility: auto, so find-in-page still works. Typical examples render in well under a second.

Without --examples the output is unchanged.

Testing

New tests/test_examples.py with small fixture examples: context-aware resolution (global, local, unknown), first-occurrence lines and counts, CLI output, and no change without the option. Full suite: 43 passed.
Built NeTEx_publication.xsd with NeTEx/examples and checked in headless Chromium: links, #L-n first-occurrence targets scrolling and highlighting, gutter clicks, no console errors.

🤖 Generated with Claude Code

https://claude.ai/code/session_01F2T5yLBWpYT83XFbEYaKPT

_Requested by **Moof** · [project thread](https://claude.ai/code/project/chan_01BmPQxcG1UuS21Gfai9Zcdh?thread=cmsg_01BmPQxcG1UuS21Gfai9ZcdhQGLX1AVXb8Bbpniv7FJ4fv)_ Adds `--examples DIR`. Every `.xml` file under the directory gets a page under `examples/` with its element names linked to their declarations, and every global element page gets an **Examples** section listing the examples that use it, each linked to the line of its first occurrence (with an occurrence count). The index gets an "All N examples" tree, like the source-file one. ## How elements are matched Each element is resolved against its parent's content model (base types, groups, compositors, substitution groups, `xsi:type`), so a local element links to the row that declares it: `<Name>` inside a `<Line>` goes to `line.html#d213-341`, not to some other `Name`. When the content model doesn't explain an element (wildcards, unknown parents, invalid examples) it falls back to a global element with the same name. On the 290 NeTEx examples against `NeTEx_publication.xsd`, 856,807 of 857,797 start tags get a link. ## Size Example pages store the document as plain text (only `&` and `<` escaped) plus a compact list of link targets per start tag, and `site.js` highlights it and adds the links in the browser. Line numbers use the CSS counter from #3. For NeTEx, the examples are 53 MB of XML and the `examples/` output is 64 MB; rendering them server-side with a link per tag would have roughly doubled that. The largest example (5 MB, 139k lines) renders in about 7 s in headless Chromium; lines are laid out in 200-line chunks with `content-visibility: auto`, so find-in-page still works. Typical examples render in well under a second. Without `--examples` the output is unchanged. ## Testing - New `tests/test_examples.py` with small fixture examples: context-aware resolution (global, local, unknown), first-occurrence lines and counts, CLI output, and no change without the option. Full suite: 43 passed. - Built `NeTEx_publication.xsd` with `NeTEx/examples` and checked in headless Chromium: links, `#L-n` first-occurrence targets scrolling and highlighting, gutter clicks, no console errors. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01F2T5yLBWpYT83XFbEYaKPT

No reviewers

No labels

No milestone

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

Reference4PT/prettyxsd!4

No description provided.

Rows
Columns