Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add IDL section and define IDL for all the members #613

Merged
merged 9 commits into from
Oct 13, 2017

Conversation

kenchris
Copy link
Collaborator

@kenchris kenchris commented Sep 20, 2017

@kenchris
Copy link
Collaborator Author

@mgiuca I did a little screw up, so new PR now :-) Comments welcome

Copy link
Collaborator

@mgiuca mgiuca left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm with some comments. Very nice work!

index.html Outdated
[NoInterfaceObject]
dictionary WebAppManifest {
TextDirectionType? dir;
USVString? lang;
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Conversely to what I said yesterday, I think "lang", "iarc_rating_id", and any other "id" or other ASCII-only fields could be DOMString instead of USVString. Practically, it probably doesn't really matter, but the WebIDL spec says "if in doubt, use DOMString".

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree. Let's change this to DOMString... it will make this less controversial if this later gets reviewed by browser folks.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done!

index.html Outdated
<pre class="idl">
[NoInterfaceObject]
dictionary ImageResource {
USVString src;
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

required?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

index.html Outdated
[NoInterfaceObject]
dictionary ImageResource {
USVString src;
DOMString sizes;
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

required?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this is required.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

src is required at least. Would you assume it is "any" if sizes is not set? Maybe file an issue?

index.html Outdated
<pre class="idl">
[NoInterfaceObject]
dictionary ServiceWorkerRegistration {
USVString src;
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

required?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

index.html Outdated
<pre class="idl">
[NoInterfaceObject]
dictionary ExternalApplicationResource {
USVString platform;
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

required

Copy link
Member

@marcoscaceres marcoscaceres left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mostly nits, but a couple of things to change... looking good.

index.html Outdated
</p>
<pre class="idl">
[NoInterfaceObject]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove [NoInterfaceObject] ... it's not an interface, it's a dictionary 😉. Also, you should never ever need to use NoInterfaceObject in a spec unless you are creating some kind of mix-in.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(I'll just emphasize, if you ever see NoInterfaceObject in a spec, yell at them... or tell me, and I will yell at them 📣😝)

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure :-) done...

index.html Outdated
@@ -1592,17 +1590,40 @@ <h3 id="applying">
<div class="issue" data-number="446"></div>
</section>
</section>
<section>
<section data-dfn-for="webappmanifest" data-link-for="webappmanifest">
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The data-dfn-for="webappmanifest" data-link-for="webappmanifest" need to match actual IDL things, so, should be "WebAppManifest".

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok, fixed

index.html Outdated
contains zero or more members. Each of the members are defined below,
as well as how their values are processed.
launched. A manifest consists of a top-level <dfn>WebAppManifest</dfn>
<a>object</a> that contains zero or more members.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's a dictionary, not an object.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How do you want me to refer to that then. Object is defined as part of JSON, dictionary is not:

  <p>
    As the manifest uses the JSON format, this specification relies on the
    types defined in [[!ECMA-404]] specification: namely <dfn>object</dfn>,
    <dfn>array</dfn>, <dfn>number</dfn>, <dfn>string</dfn>,
    <code>true</code>, <code>false</code>, and <code>null</code>. Strict
    type checking is not enforced by this specification. Instead, each
    member's definition specifies the steps required to process a
    particular member and what to do when a type does not match what is
    expected.
  </p>

index.html Outdated
as well as how their values are processed.
launched. A manifest consists of a top-level <dfn>WebAppManifest</dfn>
<a>object</a> that contains zero or more members.
Each of the members are defined below, as well as how their values are processed.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: make sure you run tidy over the doc.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Any info on this tidy and how to install/run it?

@@ -1612,45 +1633,49 @@ <h3 id="applying">
<code>dir</code> member
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you replace this with: <dfn>dir</dfn>member, and the same for the rest?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you won't need <code>, ReSpec will automatically code them.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I actually think it was done this way so that you dont have cursive in the headers, which looks stupid. The next line does the dfn

index.html Outdated
<p>
The <dfn>directionality-capable members</dfn> are:
</p>
<ul>
<li>
<a><code>description</code> member</a>.
<a><code>description</code></a> member.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/<a><code>description</code></a> member./<a>description</a> member.

Same for the rest. You should never need <code> anywhere.

index.html Outdated
The <dfn data-lt="text-direction value">text-direction values</dfn>
are the following, implying that the value of the
The <dfn data-lt="text-direction value">text-direction values</dfn> defined by
<dfn>TextDirectionType</dfn>, are the following, implying that the value of the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The TextDirectionType should have it's own top-level section.

index.html Outdated
@@ -2090,8 +2124,8 @@ <h3 id="applying">
<code>orientation</code> member
</h3>
<p>
The <dfn id="member-orientation"><code>orientation</code>
member</dfn> is a <a>string</a> that serves as the <a>default
The <dfn><code>orientation</code></dfn>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/<dfn><code>orientation</code></dfn>/<dfn>orientation</dfn> member

As above, the dfn for this should occur inside a h3 element in its own section.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The above applies for all the things below.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes I can remove from inside and , doing

index.html Outdated
[NoInterfaceObject]
dictionary ImageResource {
USVString src;
DOMString sizes;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this is required.

index.html Outdated
@@ -1261,7 +1259,7 @@ <h3 id="navigation-scope-security-considerations">
</p>
<p>
A <a>manifest</a> is obtained and applied regardless of the
<a><code>media</code></a> attribute of the <a><code>link</code>
<a>media</a> attribute of the <a><code>link</code>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: seems you missed a closing </a>. Also, please remove the <code>.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

its there :-) comes a bit later

index.html Outdated
@@ -1574,7 +1572,7 @@ <h3 id="applying">
<div>
<p>
Please note that the <a>start URL</a> is not necessarily the value
of the <a><code>start_url</code> member</a>: the user or user agent
of the <a data-link-for="WebAppManifest"><code>start_url</code></a> member: the user or user agent
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bit cleaner, you can do:

 <a data-tl="WebAppManifest.start_url">start_url</a>

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok!

index.html Outdated
@@ -1592,17 +1590,39 @@ <h3 id="applying">
<div class="issue" data-number="446"></div>
</section>
</section>
<section>
<section data-dfn-for="WebAppManifest" data-link-for="WebAppManifest">
<h2>
Manifest and its members
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should change to:

<h2>
 <dfn>WebAppManifest</dfn> dictionary 
</h2> 

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

index.html Outdated
launched. A manifest consists of a top-level <a>object</a> that
contains zero or more members. Each of the members are defined below,
as well as how their values are processed.
launched. A manifest consists of a top-level <dfn>WebAppManifest</dfn>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See comment above... so here <a>WebAppManifest</a>

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually, " A manifest consists of a top-level..." is redundant... remove this sentence. The WebIDL itself already says this.

index.html Outdated
</p>
<pre class="idl">
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: I prefer seeing the IDL before the description... "an IDL block speaks a thousand words" 😂

index.html Outdated
@@ -2090,15 +2121,15 @@ <h3 id="applying">
<code>orientation</code> member
</h3>
<p>
The <dfn id="member-orientation"><code>orientation</code>
member</dfn> is a <a>string</a> that serves as the <a>default
The <dfn>orientation</dfn>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: the <dfn>orientation</dfn> and so on, should all be defined inside the h3s... like this:

<h3>
  <dfn>orientation</dfn> member 
</h3>
<p>The <a>orientation</a> member bla bla..</p>

Applies to all of the ones below...

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

but that makes them all cursive :(

@@ -2995,13 +3035,13 @@ <h3 id="applying">
</pre>
</div>
</section>
<section>
<section data-dfn-for="imageresource">
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

<section data-dfn-for="ImageResource" data-link-for="ImageResource">

index.html Outdated
@@ -3094,18 +3134,18 @@ <h3 id="applying">
</li>
</ol>
</section>
<section>
<section data-dfn-for="imageresource">
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You shouldn't need:

data-dfn-for="imageresource"

ReSpec will find it from the parent section.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe it should, but it doesn't ... removing this and I get one more error

index.html Outdated
@@ -3234,41 +3274,40 @@ <h3 id="applying">
Each member specifies which object a multi-purpose member can be used
with.
</p>
<section>
<section data-dfn-for="ExternalApplicationResource" data-link-for="ExternalApplicationResource">
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

platform should be defined in the ExternalApplicationResource section. If this is a shared definition, then we should make a note that two things share the same definition.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe you can help me wth that in a follow up

@@ -3472,11 +3517,20 @@ <h3 id="applying">
</section>
<section>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add:
data-dfn-for= "ExternalApplicationResource" and data-link-for="ExternalApplicationResource"

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please make sure all sections that define IDL things have both.

@marcoscaceres
Copy link
Member

So... although we can define processing in IDL, we need to be careful if we are going to expose these on the web. In particular, “foo_bar” property names would make this API inconsistent with the rest of the platform.

It’s a bit similar (but obviously not the same) as CSS in JS, where “foo-bar” becomes “fooBar”. See casing rules https://w3ctag.github.io/design-principles/#casing-rules

@kenchris kenchris force-pushed the idl branch 2 times, most recently from 2df72da to 1e6068f Compare September 28, 2017 16:06
index.html Outdated
</li>
<li>If <a>Type</a>(<var>value</var>) is not "string":
<li>If <a>Type</a>(<var>V</var>) is <code>String</code>:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

how come you changed these? I can live with them, but single letter attributes are not my favorite.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like them shorter, makes it easier for me to read, plus aligned with WebIDL spec

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

plus aligned with WebIDL spec

That's something I'm hoping to fix. It's a dreadful practice.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree. It gets really confusing because you always need to go back to look up what something was. Also, the upper-case thing makes it look like a constant.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK guys I will change it :-) "value" it is

@marcoscaceres
Copy link
Member

🤔 overall, something doesn't feel right about how we are going about this... What I was expecting was:

  • Bytes over the wire => UTF-8 text => JSON Object => IDL Conversion => member normalization => return idlObejct.

I need to think a bit more.

@marcoscaceres
Copy link
Member

To be bit more clear: we need to look at each member and see what kind of normalization we need to do (if any). I was expecting to see a fairly massive reduction in spec text, because at lot of the processing algorithms should go away when the do the IDL conversion.

@kenchris
Copy link
Collaborator Author

kenchris commented Oct 2, 2017

I discussed some of this processing with @tobie so he might have ideas

@tobie
Copy link
Member

tobie commented Oct 2, 2017

So "parse JSON from bytes" => ES => IDL Conversion. That's easy. What you do after depends on a lot of factors. What you want to work with (JSON, WebIDL, JS?), wether there's going to be JS APIs involved in the future, etc.

Copy link
Collaborator

@mgiuca mgiuca left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi Ken,

I've done a fairly thorough review of the changes. Here are my thoughts.

index.html Outdated
result of running the <a>steps for processing the
<code>orientation</code> member</a> with <var>manifest</var> and
<var>display mode</var> as arguments.
<li>Let <a>WebAppManifest</a> <var>manifest</var> be the result of
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think you should not literally say "converting json to IDL dictionary value"; although it's obvious from context, that doesn't explicitly state which dictionary type you are converting to. (In WebIDL, the algorithm is called "An ECMAScript value V is converted to an IDL dictionary type value" -- emphasis mine, meaning, this is the algorithm whenever a value is converted to a type which is declared as a dictionary).

So you should write:

Let <var>manifest</var> be the result of <a data-dfn="to-idl-dictionary-value">converting</a> <var>json</var> to a <a>WebAppManifest</a>.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@tobie Could you confirm?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, your want to convert to that particular dictionary type. Not dictionaries in general. The json var is an ES object at this point, right?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes, it should be - that is at least the intent :-)

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

index.html Outdated
<li>Let <var>language</var> of <var>parsed manifest</var> be the
result of running the <a>steps for processing the <code>lang</code>
<li>Let <var>manifest["<a>display</a>"]</var> be the result of
running the <a>steps for post-processing the <code>display</code>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why not have the "steps for post-processing" each field take the field value, instead of the entire manifest?

So here it would say "running the steps for post-processing the display member with manifest["display"] as the argument", and then later on where that is defined, it would say "The algorithm takes a DisplayModeType value as an argument, and returns a DisplayModeType." Seems a bit cleaner this way.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a really good suggestion... now that we have explicit types, we should definitely make use of them.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that is a good idea too, but let's make that a follow up patch.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Up to you, but it seems it would actually make this patch smaller if you did it now (i.e., you would delete more lines without adding any).

index.html Outdated
</h2>
<pre class="idl">
dictionary WebAppManifest {
TextDirectionType? dir;
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why are all of these types nullable (ending in ?)?

Dictionary members are always optional unless otherwise specified. Adding ? means the user can explicitly specify null as a value, which I don't think we want. So I would remove all the ?s.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Because you don't have to have these declared in your manifest, they are optional. I was looking for optional in the web idl spec, but I see your point that they are all optional because of them being in a dict. This means that I will have to change most of the algorithms again though :)

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

index.html Outdated
result of running the <a>steps for processing the
<code>description</code> member</a> with <var>manifest</var> as the
argument.
<li>Let <var>manifest["<a>start_url</a>"]</var> be the result of
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So we're removing the Trim() logic for all the strings (except categories... why?). I'm not really comfortable with this until we know whether it will break sites in the wild.

Chromium, at least, certainly does trim the strings, so we would presumably remove that logic if it was removed from the manifest. I think we need to do an analysis of how many real-world manifests contain leading or trailing whitespace in these strings, and whether it would be safe to remove the trim() step. I am looking into this now.

For now, I think we should leave it, which unfortunately means each of the strings needs a post-processing step to trim it. However, for all the trim-only members, how about instead of writing "running the steps for post-processing X", you just write "Let manifest[X] be the result of running Trim(manifest[X])". That's reasonably short.

Unfortunately, you can't trim enum values like "display" after converting to the WebAppManifest dictionary type, because it will already be a TypeError. Instead, you need to pre-process by trimming the string values in "json" before converting.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pre-processing the JSON seems really ugly, but a good fallback. Let's see what the data from your analysis says about breakage.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like we can avoid all this with this breaking trim change

index.html Outdated
sequence&lt;USVString&gt;? categories;
DOMString? iarc_rating_id;
USVString? start_url;
DisplayModeType? display;
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this can have a default "= "browser"". See discussion below.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

index.html Outdated
with <var>manifest</var>, <var>manifest URL</var>, and "screenshots"
as arguments.
</li>
<li>Return <var>parsed manifest</var>.
<li>Let <var>manifest["<a>related_applications</a>"]</var> be the
result of running the <a>steps for processing the
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why are this, and the next, ones called "processing" rather than "post-processing"?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed

index.html Outdated
<li>Let <var>id</var> be the result of running the <a>steps
for processing the <code>id</code> member of an
application</a> with <var>potential application</var>.
<li>Let <var>V'</var> be a new object created as if by the
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can this just destructively update V?

Just delete Steps 1--4, and use V instead of V'. Should be equivalent, and simpler.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could, I guess. @marcoscaceres ?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree... I'm not sure what "'" signifies there.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Very common in math books :-) but let me change

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok done

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Having an X' as the updated value for X is fine. The issue here is that you went to all this trouble to create a clone which isn't necessary if you just updated it.

Again, this looks good now and no further action required.

index.html Outdated
</ol>
</li>
</ol>
<li>Initialize <var>i</var> to be 0.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this have to be an index-based loop? Can you just write "For each element of A, e: Trim(e) and convert to ASCII lowercase"? (Optionally, "updating the value in A" if you are worried about someone taking it too literally.)

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nope. Actually WebIDL uses it this way and I was looking for examples on how to write it properly without doing indices. @tobie is there a preferred wording?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As a general rule, don't copy WebIDL's style... it's a very old spec and exhibits a ton of really bad practices (for legacy reasons).

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed

index.html Outdated
<li>
<a>Issue a developer warning</a> that the type is not
supported.
<a>Trim</a>(<var>V</var>) and convert <a>to ASCII lowercase</a>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Curious that this is the last remaining Trim(). As I said above, I think we should keep all the Trims, but if you are certain of taking them out, take this one out too.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I missed that one :-)

index.html Outdated
<a><code>categories</code> member</a>. However, the working group
maintains a <a href=
This specification does not define the particular values for
<dfn>USVString</dfn>s for a the <a>categories</a> member. However,
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Drop the "a".

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

index.html Outdated
</li>
<li>If <var>unprocessed applications</var> is an <a>array</a>, then:
<li>For <var>V</var> in <var>A</var>:
Copy link
Member

@marcoscaceres marcoscaceres Oct 3, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: please use for each, IDL sequences are just arrays, so it's nice to keep the language that maps to things in JS. Also, please don't use the bracket syntax, just use:

For each <var>relatedApp</var> in <var>manifest</var>.<a>related_applications</a>.

Then we get a link back to related_applications, and don't need to guess on the type.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed markup above.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That translates nicely to:

for(const relatedApp of manifest.related_applications) {... do stuff ... }

Or, better:

manifest.related_applications.forEach(relatedApp => ... do stuff... )

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@tobie said that we cannot use dot notation for these as it is WebIDL, have to use []

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don’t think that’s correct. Or, if it is, I’m inclined to willfully violate that. We do the same in Payment Request. And I’ve never seen any other spec use [] notation.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apparently dot notation for Web IDL is not spec'ed. I went with brackets for now, but it will be easy to change (like in follow up) when dot notation gets spec'ed

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you open a ticket against WebIDL for that? Thanks.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

USVString background_color;
USVString scope;
ServiceWorkerRegistration serviceworker;
sequence&lt;ExternalApplicationResource&gt; related_applications;
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

= false (then remove the equivalent sentence down in its section).

index.html Outdated
ServiceWorkerRegistration? serviceworker;
sequence&lt;ExternalApplicationResource&gt;? related_applications;
boolean? prefer_related_applications;
TextDirectionType dir;
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

= "auto"

index.html Outdated
boolean? prefer_related_applications;
TextDirectionType dir;
DOMString lang;
USVString name;
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thought bubble: This should possibly be required (though let's not change it right now because the existing algorithm doesn't require it, and I want to change the semantics as little as possible).

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, let me file an issue

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

index.html Outdated
<li>Let <var>language</var> of <var>parsed manifest</var> be the
result of running the <a>steps for processing the <code>lang</code>
<li>Let <var>manifest["<a>display</a>"]</var> be the result of
running the <a>steps for post-processing the <code>display</code>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Up to you, but it seems it would actually make this patch smaller if you did it now (i.e., you would delete more lines without adding any).

Copy link
Collaborator

@mgiuca mgiuca left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A couple more things can be made default. Then I am quite happy with this.

@marcoscaceres
Copy link
Member

I'm worried about the use of enums invalidating the whole manifest... We might need to make those DOMStrings instead of enums (particularly for backwards compat in the future).

Copy link
Member

@marcoscaceres marcoscaceres left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm ok to go with this for now - we can experiment a bit. We need to start adding test tho.

@kenchris
Copy link
Collaborator Author

Yes, I agree. Didn't you have some tests we can start with?

@kenchris kenchris merged commit fdb8dfb into w3c:gh-pages Oct 13, 2017
@marcoscaceres
Copy link
Member

The tests I have are very Gecko specific. We will need to write new ones. It will be a good opportunity to review the spec tho.

@mgiuca mgiuca mentioned this pull request Sep 20, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants