Editorial: Refine link-element section readability #2354

sideshowbarker · 2017-02-13T03:34:22Z

The section of the spec on the link element is long and a bit complicated.
This editorial change does some reorganization to make it more usable/readable
both for implementors and authors. It restructures it into the following parts:

Intro and info for required attributes: href, rel, and itemprop
media, type, hreflang, title (content attributes from HTML4 & before)
as, crossorigin, etc. (content attributes added to link after HTML4)
IDL attributes and which content attributes they correspond to
UA requirements: Processing the media attribute
UA requirements: Processing the type attribute
UA requirements: Activation behavior of link elements that create hyperlinks
UA requirements: Obtaining a resource from a link element
UA requirements: Providing users with a means to follow link hyperlinks
UA requirements: Processing Link headers
The LinkStyle interface

Before this change the UA requirements for implementors were intermingled among
the document-conformance/informational parts for authors (1, 2, 3 above), and
not called out with headings of any kind — which made the section less
usable/readable both for implementors and authors.

This change doesn’t add or alter any normative requirements; it just moves a few
paragraphs around, adds some headings, and alphabetically re-orders some things.

domenic · 2017-02-15T21:00:36Z

@sideshowbarker sorry, can you rebase this now that #2356 is merged?

sideshowbarker · 2017-02-16T04:03:29Z

@sideshowbarker sorry, can you rebase this now that #2356 is merged?

Yup, just now rebased and pushed

domenic

This is great; upon reviewing the two versions side by side, I am convinced this is a huge improvement. It does not depart from existing structure in the ways I feared.

I left some specific comments here. Also on overall structure, I think maybe the sections should go:

Processing the media attribute
Processing the type attribute
Obtaining a resource from a link element
Processing `Link` headers
Providing users with a means to follow hyperlinks created using the link element

(see individual comments for what happened to the LinkStyle and Activation behavior sections)

domenic · 2017-02-17T23:03:38Z

source

   <dd><code data-x="attr-link-hreflang">hreflang</code></dd>
+   <dd><code data-x="attr-link-media">media</code></dd>


If we're rearranging, I wonder if we'd want to group all the type-specific ones (as, scope, sizes, usecache, workertype) together at the bottom and by type. I think that could work especially well in the prose below where we define each attribute, maybe with a <hr> separating the generic ones from the rel-specific ones. Alternately, see my idea below of moving the attribute definitions for rel-specific attributes into the rel sections.

Yeah, OK, looking at this again, I do think the optimal order for this particular list at least is going to be:

href, crossorigin, rel, media, nonce, integrity, hreflang, type, referrerpolicy (either in that order---the original order---or alphabetized)

sizes

as

scope, usecache, workertype

color

And I think that'd be good for the definitions of each attribute too. They don't have to follow the same order as this list (especially the first set), but they should be grouped together and the groups should be in that order, with <hr>s separating them.

domenic · 2017-02-17T23:08:39Z

source

-  <p>The semantics of the protocol used (e.g. HTTP) must be followed when fetching external
-  resources. (For example, redirects will be followed and 404 responses will cause the external
-  resource to not be applied.)</p>
+  <p>The <code data-x="attr-link-sizes">sizes</code> attribute is used with the <code


I guess we should be consistent and put the <dfn>s up in this section, instead of down in the rel sections, for rel-specific attributes? Right now all but sizes have their <dfn> up here, it looks like. I'd also be OK with moving all the rel-specific attributes to their appropriate rel sections.

<p>The <code data-x="attr-link-sizes">sizes</code> attribute is used with the <code

I guess we should be consistent and put the <dfn>s up in this section, instead of down in the rel sections, for rel-specific attributes?

Yes

Right now all but sizes have their <dfn> up here, it looks like.

Yeah, thanks for catching that.

domenic · 2017-02-17T23:10:14Z

source


  <hr>
+  <div w-nodev>


You can keep the <hr> inside the nodev section too.

<hr> <div w-nodev>

You can keep the <hr> inside the nodev section too.

OK, moved

domenic · 2017-02-17T23:11:40Z

source


-   <li><p>If the <code data-x="attr-link-href">href</code> attribute's value is the empty string,
-   then abort these steps.</p></li>
+  <p id="default-media">The default, if the <code data-x="attr-link-media">media</code> attribute is


I think this goes in the processing model section, probably?

<p id="default-media">The default, if the <code data-x="attr-link-media">media</code> attribute is

I think this goes in the processing model section, probably?

Yes, moved

domenic · 2017-02-17T23:16:40Z

source

-  <p>The IDL attribute <dfn><code data-x="dom-link-referrerPolicy">referrerPolicy</code></dfn> must
-  <span>reflect</span> the <code data-x="attr-link-referrerpolicy">referrerpolicy</code>
-  content attribute, <span>limited to only known values</span>.</p>
+  <h5>Providing users with a means to follow hyperlinks created using the <code>link</code>


I think the section on activation behavior for link elements that create hyperlinks can be merged into this section (probably at the bottom).

I think the section on activation behavior for link elements that create hyperlinks can be merged into this section (probably at the bottom).

Yup, made it so

domenic · 2017-02-17T23:19:39Z

source

  </div>

+  <h5>The <code>LinkStyle</code> interface</h5>


I don't think these examples are related to LinkStyle; they are instead just the usual "examples go at the bottom of an element's section".

What I would do is completely remove this sentence about LinkStyle; it's redundant with the normative IDL. Then we could move these examples into the section on Link type "alternate" and Link type "stylesheet". Maybe we can even add a sentence (probably in the intro, before any subsections) advising people to check out #linkTypes for examples of using the link element.

<h5>The <code>LinkStyle</code> interface</h5>

I don't think these examples are related to LinkStyle

Thanks yeah you’re right of course. Thanks for catching that.

What I would do is completely remove this sentence about LinkStyle; it's redundant with the normative IDL.

Yup, removed

Then we could move these examples into the section on Link type "alternate" and Link type "stylesheet".

Yes—so moved

sideshowbarker · 2017-04-03T06:13:50Z

(Just rebased against master today; still need to make changes in response to review comments)

The section of the spec on the `link` element is long and a bit complicated. This editorial change does some reorganization to make it more usable/readable both for implementors and authors. It restructures it into the following parts: 1. Intro and info for required attributes: `href`, `rel`, and `itemprop` 2. `media`, `type`, `hreflang`, `title` (content attributes from HTML4 & before) 3. `as`, `crossorigin`, etc. (content attributes added to `link` after HTML4) 4. IDL attributes and which content attributes they correspond to 5. UA requirements: Processing the `media` attribute 6. UA requirements: Processing the `type` attribute 7. UA requirements: Activation behavior of link elements that create hyperlinks 8. UA requirements: Obtaining a resource from a link element 9. UA requirements: Providing users with a means to follow link hyperlinks 10. UA requirements: Processing `Link` headers 11. The LinkStyle interface Before this change the UA requirements for implementors were intermingled among the document-conformance/informational parts for authors (1, 2, 3 above), and not called out with headings of any kind — which made the section less usable/readable both for implementors and authors. This change doesn’t add or alter any normative requirements; it just moves a few paragraphs around, adds some headings, and alphabetically re-orders some things.

* Drop redundant section about LinkStyle (WebIDL already covers it) * Move examples to point of use (and where other examples already are)

sideshowbarker · 2017-04-04T01:45:49Z

Also on overall structure, I think maybe the sections should go:

Processing the media attribute

Processing the type attribute

Obtaining a resource from a link element

Processing `Link` headers

Providing users with a means to follow hyperlinks created using the link element

OK, changed to that order

domenic

Looking good. I did re-confirm my ordering thoughts.

domenic · 2017-04-04T03:10:54Z

source

   <dd><code data-x="attr-link-hreflang">hreflang</code></dd>
+   <dd><code data-x="attr-link-media">media</code></dd>


Yeah, OK, looking at this again, I do think the optimal order for this particular list at least is going to be:

href, crossorigin, rel, media, nonce, integrity, hreflang, type, referrerpolicy (either in that order---the original order---or alphabetized)

sizes

as

scope, usecache, workertype

color

domenic · 2017-04-04T03:15:26Z

source

   <dd><code data-x="attr-link-hreflang">hreflang</code></dd>
+   <dd><code data-x="attr-link-media">media</code></dd>


And I think that'd be good for the definitions of each attribute too. They don't have to follow the same order as this list (especially the first set), but they should be grouped together and the groups should be in that order, with <hr>s separating them.

sideshowbarker · 2017-04-04T06:35:27Z

OK, re-ordered the attributes per #2354 (comment) and #2354 (comment)

Take a look and if I overlooked anything lemme know.

Hyperlink some naked occurrences of the dfn’ed term “external resource link”. And as long as we’re in here, might as well re-wrap a couple of long lines.

domenic

This LGTM; all my comments have been addressed (except one more minor ordering thing I noted). I might do another pass tomorrow but if I find anything I'm sure it'll be minor enough to just push commits myself.

@zcorpan, do you want to take a look too?

domenic · 2017-04-04T12:34:21Z

source

   <dd><code data-x="attr-link-referrerpolicy">referrerpolicy</code></dd>
+   <dd><code data-x="attr-link-as">as</code></dd>
   <dd><code data-x="attr-link-scope">scope</code></dd>


Put scope with usecache/workertype?

Put scope with usecache/workertype?

oofs—yeah, thanks for catching that; fixed

For consistency with hyperlinking added in the previous commit for the term “external resource link”, also add some hyperlinking in a few places for the term “hyperlink”. Plus, hyperlink a couple more references to “external resource link”.

zcorpan

Did not review carefully but it seems this is in a good state to merge.

All pre-existing issues before this PR, but let's get them in while we're here

…852) Fix #822 * Reflow the links section to match sideshowbarker's proposed changes from whatwg/html#2354 * Fix 'browser.include' file that mysteriously got flipped to ANSI encoding...

sideshowbarker force-pushed the sideshowbarker/link-element-reorganize branch 2 times, most recently from 615719e to fd8c7b2 Compare February 13, 2017 03:40

sideshowbarker force-pushed the sideshowbarker/link-element-reorganize branch from fd8c7b2 to 1caf6ab Compare February 16, 2017 04:02

domenic reviewed Feb 17, 2017

View reviewed changes

domenic assigned sideshowbarker Feb 22, 2017

sideshowbarker mentioned this pull request Mar 17, 2017

Refine link-element section readability w3c/html#822

Closed

sideshowbarker force-pushed the sideshowbarker/link-element-reorganize branch from 1caf6ab to b1646c3 Compare April 3, 2017 06:12

sideshowbarker force-pushed the sideshowbarker/link-element-reorganize branch from b1646c3 to 65b584d Compare April 3, 2017 06:20

sideshowbarker added 3 commits April 3, 2017 17:51

Respond to review comments

2239e97

* Drop redundant section about LinkStyle (WebIDL already covers it) * Move examples to point of use (and where other examples already are)

Consolidate extra alternate+hreflang+type examples

c59fc70

Re-order one section, merge another

9f4fddb

Move link[sizes] dfn to where related dfns are

da099b3

domenic reviewed Apr 4, 2017

View reviewed changes

Reorder attributes per review comments

58b9c21

Hyperlink a term + re-wrap some long lines

a9a75ad

Hyperlink some naked occurrences of the dfn’ed term “external resource link”. And as long as we’re in here, might as well re-wrap a couple of long lines.

domenic approved these changes Apr 4, 2017

View reviewed changes

sideshowbarker added 2 commits April 4, 2017 22:01

Hyperlink an instance of the term “link type”

e40b329

sideshowbarker mentioned this pull request Apr 4, 2017

Define the the term “the external resource is to be applied” #2503

Closed

zcorpan approved these changes Apr 4, 2017

View reviewed changes

sideshowbarker and others added 2 commits April 4, 2017 22:49

Fix attribute ordering

43229ca

Minor consistification

2da12f6

All pre-existing issues before this PR, but let's get them in while we're here

domenic merged commit 9d0d388 into master Apr 6, 2017

domenic deleted the sideshowbarker/link-element-reorganize branch April 6, 2017 06:22

domenic added the topic: link label Jun 15, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Editorial: Refine link-element section readability #2354

Editorial: Refine link-element section readability #2354

sideshowbarker commented Feb 13, 2017

domenic commented Feb 15, 2017

sideshowbarker commented Feb 16, 2017

domenic left a comment

domenic Feb 17, 2017

domenic Apr 4, 2017

domenic Apr 4, 2017

domenic Feb 17, 2017

sideshowbarker Apr 4, 2017 •

edited

Loading

domenic Feb 17, 2017

sideshowbarker Apr 4, 2017

domenic Feb 17, 2017

sideshowbarker Apr 4, 2017

domenic Feb 17, 2017

sideshowbarker Apr 4, 2017

domenic Feb 17, 2017

sideshowbarker Apr 3, 2017

sideshowbarker commented Apr 3, 2017

sideshowbarker commented Apr 4, 2017

domenic left a comment

domenic Apr 4, 2017

domenic Apr 4, 2017

sideshowbarker commented Apr 4, 2017

domenic left a comment

domenic Apr 4, 2017

sideshowbarker Apr 4, 2017

zcorpan left a comment

		<dd><code data-x="attr-link-hreflang">hreflang</code></dd>
		<dd><code data-x="attr-link-media">media</code></dd>

Editorial: Refine link-element section readability #2354

Editorial: Refine link-element section readability #2354

Conversation

sideshowbarker commented Feb 13, 2017

domenic commented Feb 15, 2017

sideshowbarker commented Feb 16, 2017

domenic left a 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

sideshowbarker Apr 4, 2017 • edited 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

sideshowbarker commented Apr 3, 2017

sideshowbarker commented Apr 4, 2017

domenic left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sideshowbarker commented Apr 4, 2017

domenic left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zcorpan left a comment

Choose a reason for hiding this comment

sideshowbarker Apr 4, 2017 •

edited

Loading