Skip to content

Consider not outputting the Dependencies section #5919

Open
@domenic

Description

@domenic

Recent work on Wattsi/Bikeshed cross-linking reminded me of an idea I've had for some time. What if the spec output just did not contain most of https://html.spec.whatwg.org/#dependencies?

In particular, all the cases where we just list terms so as to import them into the Wattsi infrastructure are kind of annoying and a maintenance burden. We're not consistent about how we import these things (e.g. leading "The" or not; do we state the type of thing; do we group related terms together as adjacent bullets/sub-bullets/multiple dfns in the same bullet; do we alphabetize).

My proposal is that:

  • The ultimate output should contain general important sentences about our dependencies, e.g. "This specification depends on the Infra Standard" and "Implementations that support the XML syntax for HTML must support some version of XML, as well as its corresponding namespaces specification, because that syntax uses an XML serialization with namespaces". These probably don't need to be divided up into a <dl>, but could just be 5-10 paragraphs.

  • The output should not contain any definitions of terms defined in other specs.

  • The source code contains something like

    <div data-wattsi-dependencies>
    
    <dfn data-x-href="https://infra.spec.whatwg.org/#code-point">code point</dfn>
    <dfn data-x-href="https://infra.spec.whatwg.org/#code-point">character</dfn>
    <dfn data-x-href="https://encoding.spec.whatwg.org/#decode">decode</dfn>
    
    <dfn data-x-href="https://www.w3.org/TR/xml/#NT-Name">Name</dfn>
    
    <dfn data-x="concept-host" data-x-href="https://url.spec.whatwg.org/#concept-host">host</dfn>
    
    <dfn data-x="http-link" data-x-href="https://tools.ietf.org/html/rfc8288#section-3">Link</dfn>
    
    </div>

    i.e. a single block with all the definitions, listed in minimal format with no worries about consistency, grouping, grammar, etc. I propose we group them by spec and alphabetize just to make the job of adding them easier, but we don't have to.

    Then, Wattsi, uses this block like normal, but in the final output pass, removes the entire <div data-wattsi-dependencies> so that it doesn't show up in the final output.


Downsides to consider:

  • Currently by clicking on a term in the dependencies section you can see all the places it's referenced. We'd lose that.

  • Other specs have a (autogenerated) "terms defined by reference" section. I'm proposing that we lose ours. Is that OK?

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions