Re: [whatwg/url] Restructure URL rendering section and add additional guidance (#434)

annevk commented on this pull request.

Thank you for following up on this, this looks really good. I added some inline comments that I'd love your feedback on.

>  
- <li><p>Other parts of the <a for=/>URL</a> should have their sequences of
- <a>percent-encoded bytes</a> replaced with code points resulting from
- <a>percent decoding</a> those sequences converted to bytes, unless that renders those
- sequences invisible.
+ <li><p>A URL can be rendered without its <a for=url>scheme</a> if the display surface only ever
+ permits a single scheme (such as a browser feature that omits <code>https://</code> because it is
+ only enabled for secure origins). Otherwise, the scheme may be replaced or supplemented with a
+ human-readable string (e.g., "Not secure") and/or a security indicator icon.

Replacing "and/or" with a comma and tacking ", or both" at the end seems slightly preferable (and I suspect the current wording doesn't get past our tooling).

>  
- <li><p>Other parts of the <a for=/>URL</a> should have their sequences of
- <a>percent-encoded bytes</a> replaced with code points resulting from
- <a>percent decoding</a> those sequences converted to bytes, unless that renders those
- sequences invisible.
+ <li><p>A URL can be rendered without its <a for=url>scheme</a> if the display surface only ever
+ permits a single scheme (such as a browser feature that omits <code>https://</code> because it is
+ only enabled for secure origins). Otherwise, the scheme may be replaced or supplemented with a
+ human-readable string (e.g., "Not secure") and/or a security indicator icon.
+
+ <li><p>A leading <code>www</code> domain label can be omitted to simplify the host, except when it
+ is part of the <a for=host>registrable domain</a>.

This one led to some issues right? It seems this can also be problematic if the site isn't reachable without it.

>  
- <li><p>Other parts of the <a for=/>URL</a> should have their sequences of
- <a>percent-encoded bytes</a> replaced with code points resulting from
- <a>percent decoding</a> those sequences converted to bytes, unless that renders those
- sequences invisible.
+ <li><p>A URL can be rendered without its <a for=url>scheme</a> if the display surface only ever
+ permits a single scheme (such as a browser feature that omits <code>https://</code> because it is
+ only enabled for secure origins). Otherwise, the scheme may be replaced or supplemented with a
+ human-readable string (e.g., "Not secure") and/or a security indicator icon.
+
+ <li><p>A leading <code>www</code> domain label can be omitted to simplify the host, except when it
+ is part of the <a for=host>registrable domain</a>.
+
+ <li><p>Omit the port if it is a <a>default port</a>.

For those schemes the URL's port will be null in those cases, so I guess we want to say to not serialize the port when it's null.

> + <li><p>Omit the port if it is a <a>default port</a>.
+</ul>
+
+<h4 id=url-rendering-elision>Elision</h4>
+
+<p>In a space-constrained display, URLs should be elided carefully to avoid misleading the user when
+making a security decision:
+
+<ul class=brief>
+ <li><p>Ensure that at least the <a for=host>registrable domain</a> can be shown when the URL is
+ rendered (to avoid showing, e.g., <code>...examplecorp.com</code> when loading
+ <code>https://not-really-examplecorp.com/</code>).
+
+ <li><p>When the full <a for=url>host</a> cannot be rendered, elide domain labels starting from the
+ front. (Note that bidirectional text means that the front of the string may not appear at the
+ left.)

I think this might benefit from one or two examples, in particular because how it's different from the previous point is a little subtle.

>  
+ <p class="note no-backref">Unfortunately, as rendered <a for=/>URLs</a> are strings and can appear
+ anywhere, a specific bidirectional algorithm for rendered <a for=/>URLs</a> would not see wide
+ adoption. Bidirectional text interacts with the parts of a <a for=/>URL</a> in ways that can cause
+ the rendering to be different from the model. Users of bidirectional languages are thus cautioned
+ that this is to be expected, particularly in plain text environments.
+
+ <li><p>Other parts of the <a for=/>URL</a> should have their sequences of
+ <a>percent-encoded bytes</a> replaced with code points resulting from
+ <a>percent decoding</a> those sequences converted to bytes, unless that renders those
+ sequences invisible.

This is primarily about the path right? So maybe we should combine this with the bit two points above whereby we encourage only to render the host?

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/url/pull/434#pullrequestreview-216162743