Explain how syntax relates to the parser for hosts and URLs #228

annevk · 2017-02-02T13:43:16Z

Fixes #118 and fixes part of #209.

domenic

I think this is a good start in the right direction, but I am concerned about two things, given the massive confusion we've seen elsewhere:

Lack of global explanation of the difference between conformant and parseable. Some abbreviated version of https://html.spec.whatwg.org/multipage/introduction.html#conformance-requirements-for-authors, or maybe just a link to it, might be a good idea. I would envision a sibling section to "Parsers" (and into which "syntax violation" would move). It might also be good to use this to give concrete examples of the usefulness of conformance checkers for URLs; one that comes to mind is text-entry software that only recognizes or autolinks conformant URLs.
Lack of local clarity while reading specific sections. I touch on this in the review, by suggesting renames like "URL string" and "URL syntax" to include "conformant" as a prefix so that when you read them without first reading the intros you're less confused. I also think an introductory sentence reiterating the fact that this is about conformance and not parsing would be good to add to the URL syntax section.

I think there is a lot of value in the work done to separate these and maintain both concepts, but as we've seen, the spec doesn't make it easy for people to appreciate that.

domenic · 2017-02-02T16:27:10Z

url.bs

+
+<ul>
+ <li><p>The <a>host parser</a> takes an arbitrary string and returns either failure or a
+ <a for=/>host</a>. (This <a for=/>host</a> cannot be an <a>opaque host</a>, those can only be


comma should be semicolon; each half is a complete sentence

domenic · 2017-02-02T16:27:55Z

url.bs

+<a>host serializer</a> relate as follows:
+
+<ul>
+ <li><p>The <a>host parser</a> takes an arbitrary string and returns either failure or a


I wonder if you want to link to infra for strings

domenic · 2017-02-02T16:28:47Z

url.bs

+
+ <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=/>host</a>.)


copypasta "host"

domenic · 2017-02-02T16:30:37Z

url.bs

@@ -823,6 +842,27 @@ unified model would be, please file an issue.
 <!-- History behind URL as term:
     https://lists.w3.org/Archives/Public/uri/2012Oct/0080.html -->

+<p>At a high level, a <a for=/>URL</a>, <a>URL string</a>, <a>URL parser</a>, and


Reading this makes me wonder if it should be "conformant URL string" or "valid URL string" instead. A web programmer probably thinks of "a URL string" as "a string that is a URL", with an ambiguous meaning of "is" that doesn't necessarily have the nuance of conformance involved.

Similarly maybe renaming the "URL syntax" section to "Conformant URL syntax"

Related: whatwg/html#2318

Since HTML uses "valid URL" (and "valid foo" in general), maybe URL spec should use "valid URL string", and HTML can use that term directly?

annevk · 2017-02-08T14:04:51Z

Thoughts thus far:

A sibling section to "Parsers" doesn't really work since syntax doesn't require infrastructure. A "syntax violation" is really a parser concept since only the parser calls them out.
If we start renaming syntax to "Valid URLs" or "URL validity" we'd need a whole lot of accompanying changes. We'd also no longer match how HTML talks about this. I'm not sure that's an improvement.
I'm not entirely convinced the confusion is as widespread as it's made to appear. There are indeed a couple of folks with a shared background who are confused, but we've had that with HTML as well and as time passed those objections passed.

So I'm not entirely sure if I want to make more drastic changes at this point.

Things I'm open to doing:

Add a non-normative paragraph at the start of the syntax sections explaining who they are for, similar to what HTML does.

domenic · 2017-02-08T15:05:25Z

A sibling section to "Parsers" doesn't really work since syntax doesn't require infrastructure. A "syntax violation" is really a parser concept since only the parser calls them out.

Maybe renaming "Infrastructure" to "Shared concepts" then. I disagree that "syntax violation" is a parser concept; it's detected during the course of parsing, but it's much more interesting in the context of conformance checking, and the fact that conformance checking reuses the parser infrastructure is almost incidental. You could imagine a world where conformance checking uses a grammar instead, for example.

I'm not entirely convinced the confusion is as widespread as it's made to appear. There are indeed a couple of folks with a shared background who are confused, but we've had that with HTML as well and as time passed those objections passed.

I don't think the confusion has passed for HTML over time. We see implementers unaware of the difference on almost a weekly basis. To me anything we can do to make it more explicit helps the situation.

Anyway, it's fine if you don't want to change much; what's in this PR is already an improvement and we shouldn't block it.

annevk · 2017-02-08T15:09:14Z

Yeah, you're right that folks get confused by HTML too and I was wrong that I followed HTML here. HTML calls the whole setup syntax, and then distinguishes between writing and parsing. Maybe that's what URL should do. (See https://html.spec.whatwg.org/multipage/#toc-syntax.)

domenic · 2017-02-08T15:44:28Z

url.bs

+
+<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.

domenic · 2017-02-08T15:44:59Z

url.bs

+ 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"

domenic · 2017-02-08T16:12:15Z

url.bs

@@ -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.

domenic · 2017-02-08T16:12:25Z

url.bs

+<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"

domenic · 2017-02-08T16:13:26Z

url.bs

+<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?

Wouldn't work for hosts.

domenic · 2017-02-08T16:14:25Z

url.bs

 <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?

All other sections lead with "Host".

I guess "Book writing" is not that much worse than "Writing books".

domenic · 2017-02-08T16:15:46Z

url.bs

+
+ <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".

TRowbotham · 2017-02-08T21:19:25Z

url.bs

+<ul>
+ <li><p>The <a>host parser</a> takes an arbitrary string and returns either failure or a
+ <a for=/>host</a>. (This <a for=/>host</a> cannot be an <a>opaque host</a>; those can only be
+ returned through the <a>URL parser</a>.)


cdbcce6 made it so that the host parser can return an opaque host, so this note is no longer true.

Excellent point, thanks!

annevk · 2017-02-09T11:31:14Z

So we discussed terms before in #60 with @sideshowbarker and decided to rename from "parse error" then because of #59 (comment).

There's additionally the question of whether to signify both non-fatal and fatal the same way. I think we probably should signify them the same way (since it's still a requirements mismatch), but fatal has additionally the failure return value.

"Conformance violation" would work, but I don't like that we then have both "valid" and "conformance". And "conforming" seems overall like a more complicated word.

Anyone any good ideas?

domenic · 2017-02-09T14:44:33Z

"validity error" or "validation error"? Not sure if that crosses over into the line of "bad" that "validator" does.

annevk · 2017-02-09T15:06:14Z

I still don't really understand the problem with "validator". "Validation error" seems reasonable. @sideshowbarker?

sideshowbarker · 2017-02-09T16:56:10Z

"Validation error" seems reasonable.

Yes agreed

annevk · 2017-02-09T17:47:57Z

Thank you both! Getting somewhere.

Commit message:

Attempt to explain valid input better

In particular, do away with the word "syntax" as that causes lots of confusion and focus on validity instead. Also explain the relationship between the parser, serializer, model, and (valid) input.

"Syntax violation" is now known as "validation error".

Fixes #118 and fixes part of #209.

Fixes #118 and fixes part of #209.

domenic

LGTM, although re-reading this reminds me of #219 and how we should work on solving that at some point.

annevk · 2017-02-10T08:08:14Z

I kinda addressed that issue in #228 (comment). I think the duplication is fine and more clear, especially with the revised wording.

whatwg/url#228

domenic reviewed Feb 2, 2017

View reviewed changes

jasnell approved these changes Feb 2, 2017

View reviewed changes

domenic mentioned this pull request Feb 3, 2017

Clarify URL string spec reference whatwg/html#2318

Merged

annevk force-pushed the annevk/concept-relations branch from b1e3159 to 19e3ec7 Compare February 8, 2017 15:27

annevk requested review from sideshowbarker, zcorpan and domenic February 8, 2017 15:56

domenic reviewed Feb 8, 2017

View reviewed changes

TRowbotham reviewed Feb 8, 2017

View reviewed changes

annevk force-pushed the annevk/concept-relations branch from e889fbb to 56b60c5 Compare February 9, 2017 11:17

annevk added 9 commits February 9, 2017 19:08

Explain how syntax relates to the parser for hosts and URLs

316d379

Fixes #118 and fixes part of #209.

nits

f20f2e4

syntax > writing

dc7f80c

stop referring to syntax

e9f98d8

add a valid prefix, hyphens to IPvX-address

6fe7bcc

also rename recent changes

9d46dd9

address most feedback

25bc678

writing violation -> validation error

cf5f7d2

Also rename writingViolationFlag / syntaxViolationFlag

8fc66a8

annevk force-pushed the annevk/concept-relations branch from cb49e6f to 8fc66a8 Compare February 9, 2017 18:09

domenic approved these changes Feb 9, 2017

View reviewed changes

annevk mentioned this pull request Feb 10, 2017

Is failure ever not a syntax violation? #219

Closed

annevk merged commit 50cb9ab into master Feb 10, 2017

annevk deleted the annevk/concept-relations branch February 10, 2017 08:10

rmisev added a commit to upa-url/upa that referenced this pull request May 24, 2020

// "Syntax violation" --> "validation error"

3446eeb

whatwg/url#228

rmisev added a commit to upa-url/upa that referenced this pull request May 24, 2020

// syntaxViolationFlag --> validationErrorFlag

27b6382

whatwg/url#228

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Explain how syntax relates to the parser for hosts and URLs #228

Explain how syntax relates to the parser for hosts and URLs #228

annevk commented Feb 2, 2017 •

edited by pr-preview bot

Loading

domenic left a comment

domenic Feb 2, 2017

domenic Feb 2, 2017

domenic Feb 2, 2017

domenic Feb 2, 2017

domenic Feb 2, 2017

zcorpan Feb 3, 2017

annevk commented Feb 8, 2017

domenic commented Feb 8, 2017

annevk commented Feb 8, 2017

domenic Feb 8, 2017

domenic Feb 8, 2017

domenic Feb 8, 2017

domenic Feb 8, 2017

domenic Feb 8, 2017

annevk Feb 8, 2017

domenic Feb 8, 2017

annevk Feb 8, 2017

domenic Feb 8, 2017

domenic Feb 8, 2017

TRowbotham Feb 8, 2017

annevk Feb 9, 2017

annevk commented Feb 9, 2017

domenic commented Feb 9, 2017

annevk commented Feb 9, 2017

sideshowbarker commented Feb 9, 2017

annevk commented Feb 9, 2017

domenic left a comment

annevk commented Feb 10, 2017

Explain how syntax relates to the parser for hosts and URLs #228

Explain how syntax relates to the parser for hosts and URLs #228

Conversation

annevk commented Feb 2, 2017 • edited by pr-preview bot Loading

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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

annevk commented Feb 8, 2017

domenic commented Feb 8, 2017

annevk commented Feb 8, 2017

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

annevk commented Feb 9, 2017

domenic commented Feb 9, 2017

annevk commented Feb 9, 2017

sideshowbarker commented Feb 9, 2017

annevk commented Feb 9, 2017

domenic left a comment

Choose a reason for hiding this comment

annevk commented Feb 10, 2017

annevk commented Feb 2, 2017 •

edited by pr-preview bot

Loading