From 18ab5a91adfdfb133e9d47cd82ad6d1e7d3b8505 Mon Sep 17 00:00:00 2001 From: randogoth Date: Sun, 11 Oct 2026 15:05:42 +0300 Subject: [PATCH] docs: describe the directory and record the known issues --- doc/NOTES.md | 39 +++++++++++++++++++++++++++++++++++++++ doc/SPEC.md | 8 +++++--- 2 files changed, 44 insertions(+), 3 deletions(-) create mode 100644 doc/NOTES.md diff --git a/doc/NOTES.md b/doc/NOTES.md new file mode 100644 index 0000000..c2eaa23 --- /dev/null +++ b/doc/NOTES.md @@ -0,0 +1,39 @@ +# Known issues + +Things that are true of the implementation but not yet of the spec, or the other +way round. Each one is a decision waiting to be made, not a bug to work around. + +## The hosted XHTML-MP DTD cannot validate offline + +Section 9.1 says the project hosts a copy of the original XHTML-MP 1.2 DTD "so +validation never depends on the Open Mobile Alliance's server." The copy in +`dtd/xhtml-mobile12.dtd` is only the OMA *driver*: it pulls about twenty-two +modules from `http://www.w3.org/TR/xhtml-modularization/DTD/*.mod`, one module +from openmobilealliance.org, and a relative `xhtml-mobile12-model-1.mod` that is +not in this repository. Hosting it therefore removes one network dependency and +leaves the rest. + +It does not affect Mews validation. `dtd/mews-0.1.dtd` is self-contained, and +the only thing the declared doctype has to provide is the character entity set, +which `mews/lint.py` builds in memory from `html.entities` — the same 252 names, +no network, nothing to keep in sync. + +Two ways out, when it matters: reword 9.1 to say the hosted copy is a +convenience, or vendor the modules under `dtd/xhtml-mobile12/` with a public-ID +resolver. Only the second would let a test prove section 3's claim that every +page passing the Mews DTD is also valid XHTML-MP 1.2 apart from `lang` and +`dir`. + +## The head element order is normative, and surprising + +`` means the title comes first +and at least one meta follows it, so a `` before the first `` is +invalid. That follows section 3.3, but 3.3 does not say the order is normative, +and the validator's message has to explain it. Worth a sentence in the spec. + +## The copies under mews/data + +`mews/data/mews-0.1.css` and `mews/data/mews-0.1.dtd` are copies of the +canonical files at the repository root and in `dtd/`. They exist so the +validator finds them when it is installed as a wheel with nothing else on disk. +`tests/test_data.py` fails if a copy drifts from its original. diff --git a/doc/SPEC.md b/doc/SPEC.md index 3dcaa06..1519071 100644 --- a/doc/SPEC.md +++ b/doc/SPEC.md @@ -241,7 +241,7 @@ A Mews page SHOULD link the default stylesheet with exactly one element: ``` -Sites SHOULD host their own copy rather than linking a central URL, so no single server sees traffic across all sites. Authors MUST NOT modify their copy, except to add @font-face rules that load font files from their own site; any other change makes the page non-conforming. +Sites SHOULD host their own copy rather than linking a central URL, so no single server sees traffic across all sites. A copy on another site is also a resource from another site, which section 7.4 forbids; the project's own copy at `mews.page/mews-0.1.css` is the one exception a validator tolerates, and it warns about it. Authors MUST NOT modify their copy, except to add @font-face rules that load font files from their own site; any other change makes the page non-conforming. ### 5.3 Body variants @@ -344,13 +344,15 @@ A page conforms when it passes two checks: 1. **The Mews DTD.** The XHTML-MP 1.2 DTD, restricted as in section 4 and extended with lang and dir, published with each spec version at `mews.page/dtd/mews-.dtd` (this one at `mews.page/dtd/mews-0.1.dtd`). It encodes the permitted elements and attributes (4.1), the head rules (3.3), the body variant values (5.3) and the ban on nested tables (4.2). 2. **Rule checks.** The rules a DTD cannot express: image sources, formats and sizes (4.2), page size (4.3), the default stylesheet link and its unmodified copy (5.2), and no resources from other sites (7.4). -Apart from lang and dir, every page that passes the Mews DTD is also valid XHTML-MP 1.2. Pages keep the XHTML-MP doctype from 3.1; the Mews DTD is used only by validators. The project SHOULD publish a validator that runs both checks and reports each failure with its section number. +Apart from lang and dir, every page that passes the Mews DTD is also valid XHTML-MP 1.2. Pages keep the XHTML-MP doctype from 3.1; the Mews DTD is used only by validators. The project publishes a validator that runs both checks and reports each failure with its section number, at mews.page/check and as a command line tool. The project also hosts a copy of the original XHTML-MP 1.2 DTD at `mews.page/dtd/xhtml-mobile12.dtd`, so validation never depends on the Open Mobile Alliance's server. Browsers and clients MUST NOT fetch either DTD. ### 9.2 Directory -The Mews directory at mews.page lists only sites whose pages pass validation. Listed sites are rechecked periodically, and a site that stops conforming is notified before it is removed. +The Mews directory at mews.page/directory lists only sites whose pages pass validation. Anyone may submit a page address: the page is fetched and checked, and a page that passes lists its site at once. Nobody reviews submissions, and the directory holds no contact details. + +Listed sites are rechecked periodically. A site whose page stops conforming is removed; submitting the page again once it is fixed lists the site again straight away. A site the checker simply cannot reach is retried for a few days before it is removed, because downtime is not a conformance failure. The checks say nothing about what a site publishes, so the project also removes a listing on request. ### 9.3 Versioning