Skip to content
This repository was archived by the owner on Sep 24, 2026. It is now read-only.
This repository was archived by the owner on Sep 24, 2026. It is now read-only.

README overstates tree-construction completeness (frameset modes, <template> simplification undocumented) #1

Description

@casoon

Problem

The README's Status section says:

The tokenizer (§13.2.5) and tree-construction algorithm (§13.2.6 — all insertion modes, adoption agency, foster parenting, foreign content) are implemented and wired end to end.

This reads as "full WHATWG HTML5 tree construction", but two real gaps aren't mentioned:

  • Frameset-related insertion modes ("in frameset", "after frameset", "after after frameset") are not implemented at all. A <frameset> start tag is silently ignored rather than switching modes (see TreeBuilder::process_token_in_body's frameset arm).
  • <template> is treated as an ordinary element — no inert content-fragment semantics, no template insertion-modes stack, no shadow-root handling (§13.2.6.4.4's simplification, documented in code comments but not in the README).

Both are deliberate, evidence-based scope decisions (frameset: html-conform's RELAX NG schema can never validate a frameset document; template: no evidence html-conform needs real template-content semantics) — not oversights. But the README doesn't say so, which makes the crate look more complete than it is to anyone evaluating it from outside.

Solution path

  1. Add a short "Known limitations" subsection to README.md's Status section (or expand Scope), stating explicitly:
    • Frameset-related insertion modes are not implemented; <frameset>/<frame>/<noframes> content is not parsed per spec.
    • <template> is parsed as a plain element; no template content model.
    • Point to the rationale (html-conform's actual schema/usage, not "not implemented yet for no reason").
  2. If html-conform's needs ever change (e.g. it starts validating documents that can contain <frameset>, or gains real <template>-content test cases), revisit the scope decision explicitly — don't silently start half-implementing either.
  3. Optional: mirror the same disclosure in Cargo.toml's description if it ever gets more elaborate, and in any future crates.io listing.

No code changes needed for this one — it's a documentation-accuracy fix.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions