Editorial: stop listing terms defined in other specifications #6810

domenic · 2021-06-28T19:51:24Z

Instead, those terms are defined in a "database" of tags that don't make it to the output, and as such don't require so much manual curation. Closes #5919. This should make contributing to HTML much easier.

This also fixes a few cross-links and updates some of the prose in what's left of the dependencies section.

I will leave a self-review commenting on particularly-interesting things to review.

See https://whatpr.org/html/6810/infrastructure.html#dependencies for the new, slimmer dependencies section.

Depends on whatwg/wattsi#145; do not merge before that gets merged.

I will help anyone with open PRs rebase past these changes, but it'd be ideal to merge this and whatwg/wattsi#145 soon so that I don't have to keep adapting to any newly-introduced references.

/browsers.html ( diff )
/browsing-the-web.html ( diff )
/canvas.html ( diff )
/common-microsyntaxes.html ( diff )
/custom-elements.html ( diff )
/dnd.html ( diff )
/dom.html ( diff )
/form-control-infrastructure.html ( diff )
/form-elements.html ( diff )
/forms.html ( diff )
/history.html ( diff )
/iframe-embed-object.html ( diff )
/image-maps.html ( diff )
/imagebitmap-and-animations.html ( diff )
/images.html ( diff )
/index.html ( diff )
/indices.html ( diff )
/infrastructure.html ( diff )
/input.html ( diff )
/interaction.html ( diff )
/interactive-elements.html ( diff )
/introduction.html ( diff )
/links.html ( diff )
/media.html ( diff )
/microdata.html ( diff )
/obsolete.html ( diff )
/origin.html ( diff )
/parsing.html ( diff )
/references.html ( diff )
/rendering.html ( diff )
/scripting.html ( diff )
/semantics-other.html ( diff )
/semantics.html ( diff )
/server-sent-events.html ( diff )
/structured-data.html ( diff )
/syntax.html ( diff )
/system-state.html ( diff )
/tables.html ( diff )
/text-level-semantics.html ( diff )
/urls-and-fetching.html ( diff )
/web-sockets.html ( diff )
/webappapis.html ( diff )
/window-object.html ( diff )
/workers.html ( diff )

Instead, those terms are defined in a "database" of <dfn> tags that don't make it to the output, and as such don't require so much manual curation. Closes #5919. This should make contributing to HTML much easier. This also fixes a few cross-links and updates some of the prose in what's left of the dependencies section.

domenic · 2021-06-28T19:51:48Z

source

+   * Do not line-wrap.
+   * For new specs, remember to add the spec to the id="references" section and add at least one
+     <ref>.
+  -->


What do people think of these instructions? Anything else helpful we could add?

I think this is sufficient.

domenic · 2021-06-28T19:52:58Z

source

+  <dfn data-x-href="https://w3c.github.io/aria/#dfn-ariamixin-getter-steps">ARIAMixin getter steps</dfn>
+  <dfn data-x-href="https://w3c.github.io/aria/#dfn-ariamixin-setter-steps">ARIAMixin setter steps</dfn>
+  <dfn data-x-href="https://w3c.github.io/aria/#dfn-role">role</dfn>
+  <dfn data-x-href="https://w3c.github.io/aria/#host_general_role">attr-aria-role</dfn>


We've discussed this previously. It seems like the ARIA spec expects the host language to define a role attribute. Since we don't do that yet, I changed from having a not-very-helpful <dfn> in the dependencies section to cross-linking to the ARIA spec's requirements on host attributes. But, we should still perhaps consider defining the attribute one day.

I don't think it makes sense for the host language to define it, tbh. Historically, I think ARIA was being way too abstract with trying to please everyone (the XML community, the RDF/Ontology community, etc.) - but I've been pushing them to move away from all that and start leveraging the DOM+HTML+Infra. We've made good progress: w3c/aria#1510

I exported the role attribute (somewhat badly) here: w3c/aria@5aa4442

(I should have removed the "host language" text)

But now that they are more willing to embrace the DOM, we have a chance to define this right.

Related discussion:
#6890

domenic · 2021-06-28T19:59:26Z

source

@@ -1532,6 +2678,9 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute

  <p>This specification depends on <cite>Infra</cite>. <ref spec=INFRA></p>

+  <p w-nodev>The IDL fragments in this specification must be interpreted as required for conforming


I moved this here. Not sure how important it is to keep; I guess I lean toward deleting it?

It's required by Web IDL, no?

You mean, adding such a sentence is required by Web IDL? Or, conformance is required by IDL, so this sentence is redundant?

The former, but I see now that it's informative: https://heycam.github.io/webidl/#referencing. It would make sense to me if that was normative, similar to how Infra does it.

domenic · 2021-06-28T19:59:52Z

source

@@ -1879,18 +3028,6 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute



-  <h4 id="encoding-terminology">Character encodings</h4>


This section seemed like redefinitions of stuff in Encoding so I just deleted it with no replacement.

domenic · 2021-06-28T20:00:14Z

source

+  <p>This specification is massively reliant on and intertwined with other specifications, crossing
+  many layers of the technology stack. References to terms and algorithms defined in other
+  specifications are performed via inline hyperlinks. The following is a list of specifications
+  whose roles require special commentary.</p>


I rewrote this intro, replacing "This specification relies on several other underlying specifications."

domenic · 2021-06-28T20:01:04Z

source

-         <dfn data-x-href="https://infra.spec.whatwg.org/#code-unit">code unit</dfn>,
-         <dfn data-x-href="https://infra.spec.whatwg.org/#string-length">length</dfn>, and
-         <dfn data-x-href="https://infra.spec.whatwg.org/#string-code-point-length">code point length</dfn></li>
-     <li id="case-sensitive">The string equality operations <dfn data-x-href="https://infra.spec.whatwg.org/#string-is">is</dfn> and


If people are still relying on HTML's #case-sensitive, #uppercase-ascii-hex-digits, etc., this will break them. I tend to think that's OK and doesn't need any ID preservation after this much time.

domenic · 2021-06-28T20:02:16Z

source

-     <li><dfn data-x="event-pointerup" data-x-href="https://w3c.github.io/pointerevents/#the-pointerup-event"><code>pointerup</code></dfn> event</li>
-    </ul>
+    <p class="note">User agents are encouraged to implement the features described in
+    <cite>execCommand</cite>. <ref spec=EXECCOMMAND></p>


This feels a bit out of place under the DOM section... we could delete it. Shrug

domenic · 2021-06-28T20:03:37Z

source

-  several features assume that those languages and protocols are in use.</p>
+  sheet language, or scripting language. However, the language described by this specification is
+  biased towards HTTP as the network protocol, CSS as the styling language, and JavaScript as the
+  scripting language, and several features assume that those protocols and languages are in use.</p>


Removed "any of the DOM specifications" since that seems like a remnant of an older time when we called all web platform specifications "DOM". I considered replacing it with "web platform specifications" but I don't think the statement would be true anymore since e.g. we deleted Fetch from the above <dl>.

domenic · 2021-06-28T20:03:47Z

source

@@ -6552,11 +5892,15 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute

  <h4>Dynamic changes to base URLs</h4>

+  <p class="XXX">This section relies on concepts which used to be defined in <cite>DOM</cite>, but
+  no longer are. So it's not really clear what this section means. See <a
+  href="https://github.com/whatwg/dom/issues/61">whatwg/dom#61</a>.</p>


Yeah, we should fix this one day.

domenic · 2021-06-28T20:04:33Z

source

@@ -12710,7 +12054,7 @@ interface <dfn interface>DOMStringMap</dfn> {
    <p>If <var>node</var>'s <span>used value</span> of <span>'display'</span> is
    <span>block-level</span> or <span>'table-caption'</span>, then <span data-x="list
    append">append</span> 1 (a <i>required line break count</i>) at the beginning and end of
-    <var>items</var>. <ref spec=CSSDISPLAY></p>
+    <var>items</var>. <ref spec=CSSCASCADE> <ref spec=CSSDISPLAY></p>


When deleting the dependencies section I found that we then had many references that had no <ref> instances left. So I went through and added a bunch of minor ones. In some cases it's a bit random but on net it feels OK.

This keeps it near the top but avoids it ending up in (and then getting removed from) every part of the multipage spec. I assume that will help builds a little bit.

TimothyGu · 2021-06-28T21:54:24Z

I often find it useful to look for all the cross-references of a term defined in another spec. Just recently, I needed to look for all references to document's URL in HTML, which is defined in DOM. I did so by going to § 3.1 Documents and clicking on "URL".

It looks like this clean-up hides all those references in a w-nooutput block. Is it still possible to view the cross-references after this clean-up?

domenic · 2021-06-28T21:56:52Z

No, although you could imagine adding it back with JavaScript... e.g. hold down a key while you click a reference to a term.

domenic · 2021-06-30T18:20:09Z

I tried to create something like that with JavaScript but it relies on information we aren't yet putting in xrefs.json: the data-x-href (i.e. destination URL) for a given definition term.

annevk · 2021-07-21T09:41:36Z

I share @TimothyGu's concern. It can be quite useful to go to a dfn and find all the instances. As an editor I can also do that by looking at the source, but I'm not sure how many readers use that functionality. (It would be even more useful if that also worked for references as you suggest though.)

domenic · 2021-08-09T19:12:43Z

@sideshowbarker would you be able to help with this? In particular I need to get Wattsi to output a slightly different xrefs.json: Instead of

{
  "xref-name": { ... refs to it in the spec ... },
  ...
}

I need

{
  "external-xref-name": {
    "url": "https://external.example.com/#foo",
    "refs": { ... refs to it in the spec ... }
  },
  "internal-xref-name": {
    "refs": { ... refs to it in the spec ... }
  },
  ...
}

I tried to make this work in whatwg/wattsi@af692d7 but I couldn't fully figure it out. I'm unsure whether it'd be best for you to help fix that attempt or start from scratch.

sideshowbarker · 2021-08-09T22:56:42Z

@sideshowbarker would you be able to help with this?

Yup — I’ll take a look at it later today

domenic force-pushed the wattsi-dependencies branch from 2660a45 to cebbe60 Compare June 28, 2021 19:55

Fix redirects

fe7c5ca

domenic commented Jun 28, 2021

View reviewed changes

domenic added the do not merge yet Pull request must not be merged per rationale in comment label Jun 28, 2021

Move it down into the "intro" section

abadd5b

This keeps it near the top but avoids it ending up in (and then getting removed from) every part of the multipage spec. I assume that will help builds a little bit.

domenic added the spec tooling label Jun 28, 2021

annevk mentioned this pull request Jul 22, 2021

Drop export to "role" attribute #6890

Open

domenic force-pushed the main branch from 0947339 to 1b5099f Compare July 27, 2021 17:07

domenic mentioned this pull request Dec 13, 2022

Adds 'Consume User Activation of Window' via WebDriver #8609

Merged

4 tasks

domenic mentioned this pull request Nov 17, 2023

Add pagereveal event #9818

Merged

5 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Editorial: stop listing terms defined in other specifications #6810

Editorial: stop listing terms defined in other specifications #6810

domenic commented Jun 28, 2021 •

edited by pr-preview bot

Loading

domenic Jun 28, 2021

annevk Jul 21, 2021

domenic Jun 28, 2021

marcoscaceres Jul 23, 2021

domenic Jun 28, 2021

annevk Jul 21, 2021

domenic Jul 21, 2021

annevk Jul 21, 2021

domenic Jun 28, 2021

domenic Jun 28, 2021

domenic Jun 28, 2021

domenic Jun 28, 2021

domenic Jun 28, 2021

domenic Jun 28, 2021

domenic Jun 28, 2021

TimothyGu commented Jun 28, 2021

domenic commented Jun 28, 2021

domenic commented Jun 30, 2021

annevk commented Jul 21, 2021

domenic commented Aug 9, 2021

sideshowbarker commented Aug 9, 2021

		@@ -1532,6 +2678,9 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute

		<p>This specification depends on <cite>Infra</cite>. <ref spec=INFRA></p>

		<p w-nodev>The IDL fragments in this specification must be interpreted as required for conforming

		@@ -1879,18 +3028,6 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute



		<h4 id="encoding-terminology">Character encodings</h4>

Editorial: stop listing terms defined in other specifications #6810

Are you sure you want to change the base?

Editorial: stop listing terms defined in other specifications #6810

Conversation

domenic commented Jun 28, 2021 • edited by pr-preview bot Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

TimothyGu commented Jun 28, 2021

domenic commented Jun 28, 2021

domenic commented Jun 30, 2021

annevk commented Jul 21, 2021

domenic commented Aug 9, 2021

sideshowbarker commented Aug 9, 2021

domenic commented Jun 28, 2021 •

edited by pr-preview bot

Loading