docs: describe the directory and record the known issues

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
+
+`<!ELEMENT head ( title, meta, ( meta | link )* )>` means the title comes first
+and at least one meta follows it, so a `<link>` before the first `<meta>` 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.

doc/SPEC.md

@@ -241,7 +241,7 @@ A Mews page SHOULD link the default stylesheet with exactly one element:
 <link rel="stylesheet" type="text/css" href="mews-0.1.css" />
 ```
 
-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-<version>.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