Re: [whatwg/url] Explain how syntax relates to the parser for hosts and URLs (#228)

domenic commented on this pull request.



> @@ -74,6 +74,22 @@ DOM, Encoding, IDNA, and Web IDL Standards.
 number.
 
 
+<h3 id=writing>Writing</h3>
+
+<p>A <dfn oldids=syntax-violation>writing violation</dfn> indicates a non-fatal mismatch between
+input and writing requirements. User agents, especially conformance checkers are encouraged to
+report them somewhere.
+
+<div class="note no-backref">
+ <p>A <a>writing violation</a> does not mean that the parser terminates. Termination of a parser is
+ always stated explicitly, E.g., through a return statement.

lowercase e.g.

> @@ -74,6 +74,22 @@ DOM, Encoding, IDNA, and Web IDL Standards.
 number.
 
 
+<h3 id=writing>Writing</h3>
+
+<p>A <dfn oldids=syntax-violation>writing violation</dfn> indicates a non-fatal mismatch between
+input and writing requirements. User agents, especially conformance checkers are encouraged to
+report them somewhere.
+
+<div class="note no-backref">
+ <p>A <a>writing violation</a> does not mean that the parser terminates. Termination of a parser is
+ always stated explicitly, E.g., through a return statement.
+
+ <p>It is useful to signal <a>writing violations</a> as error-handling can be non-intuitive, legacy
+ user agents might not implement correct error-handling, the intent of what is written might be

missing "and"

> @@ -74,6 +74,22 @@ DOM, Encoding, IDNA, and Web IDL Standards.
 number.
 
 
+<h3 id=writing>Writing</h3>
+
+<p>A <dfn oldids=syntax-violation>writing violation</dfn> indicates a non-fatal mismatch between

Eh, this turn of phrase just seems awkward... a "violation of writing"? I think it's OK for the section to be about writing URLs, but to call it a "conformance violation" or "syntax violation" still.

> @@ -74,6 +74,22 @@ DOM, Encoding, IDNA, and Web IDL Standards.
 number.
 
 
+<h3 id=writing>Writing</h3>
+
+<p>A <dfn oldids=syntax-violation>writing violation</dfn> indicates a non-fatal mismatch between
+input and writing requirements. User agents, especially conformance checkers are encouraged to

Missing comma after "conformance checkers"

> @@ -74,6 +74,22 @@ DOM, Encoding, IDNA, and Web IDL Standards.
 number.
 
 
+<h3 id=writing>Writing</h3>
+
+<p>A <dfn oldids=syntax-violation>writing violation</dfn> indicates a non-fatal mismatch between
+input and writing requirements. User agents, especially conformance checkers are encouraged to

Again "writing requirements" is a bit of an odd turn of phrase. It could work with some explanation, probably... Maybe "requirements for writing URLs" would be enough?

>   <var>result</var>.
 </ol>
 
 
-<h3 id=host-syntax>Host syntax</h3>
+<h3 id=host-writing oldids=host-syntax>Host writing</h3>

"Writing hosts" or "Writing conformant hosts" maybe?

> +<p>At a high level, a <a for=/>URL</a>, <a>valid URL string</a>, <a>URL parser</a>, and
+<a>URL serializer</a> relate as follows:
+
+<ul>
+ <li><p>The <a>URL parser</a> takes an arbitrary string and returns either failure or a
+ <a for=/>URL</a>.
+
+ <li><p>A <a for=/>URL</a> can be seen as the in-memory representation.
+
+ <li><p>A <a>valid URL string</a> defines what input would not trigger a <a>writing violation</a> or
+ failure when given to the <a>URL parser</a>. I.e., input that would be considered conforming or
+ valid.
+
+ <li><p>The <a>URL serializer</a> takes a <a for=/>URL</a> and returns a string. (If that string
+ is then <a lt="URL parser">parsed</a>, the result will <a for=url>equal</a> the
+ <a lt="URL serializer">serialized</a> <a for=/>URL</a>.)

I don't think it will equal the serialized URL; the serialized URL is a string. Maybe "the URL that was serialized".

-- 
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/228#pullrequestreview-20790345