randogoth/mews.page
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: describe the directory and record the known issues

Browse source
This commit is contained in:
randogoth 2026-10-11 15:05:42 +03:00
parent 1e75a69381
commit 18ab5a91ad
2 changed files with 44 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

39
doc/NOTES.md Normal file
View file

@ -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.