[whatwg] Comments/questions on 4.6 Offline Web applications

[Ian Hickson]

On Sat, 6 Oct 2007, Adam Roben wrote:
>
> Here are some comments and questions about section 4.6 Offline Web 
> applications:

Thanks for the feedback! It was very useful in making the spec better. 
Please do continue reviewing the spec!


> 4.6.2
> -----
> The description of "Implicit entries" is unclear. My current 
> understanding is that the only kind of implicit entry you ever have is a 
> document that specified an application attribute on its html element. 
> The description of "The manifest" and the application cache selection 
> algorithm seem to support this. I think my confusion would be cleared up 
> if the first word in the description of "Implicit resources" were 
> "Documents" instead of "Resources".

I've changed "Resources" to "Documents", but this may end up changing 
again when I address the recently raised issue regarding the meaning of 
the word "document" in the spec. We'll see.


> Can javascript: URIs be specified in the manifest?

I guess currently this is allowed...

I'm not sure how to work around this. Blacklisting them is a bad idea, as 
we'll forget some scheme that should be black-listed (e.g. vbscript:). 
Should we just say that you can only cache files that have the same scheme 
as the manifest? I've said that for now.


> 4.6.3.1
> -------
> "Manifests must specify all the URIs that are to be cached" seems to be
> untrue: you don't have to specify the URI of any implicit resources, or of the
> manifest itself.

Well, you do. I mean, you don't for it to _work_, but you do to be 
conforming. That is, the "must" statement is not a statement of fact, it's 
a conformance criteria, and thus true by definition.

I've removed the requirement.


> It may be worth stating in this section what the behavior is when a 
> section or opportunistic caching namespace appears multiple times. The 
> parsing algorithm makes this clear, but it would be clearer still to 
> also state the behavior in this section.

Well, that would be non-conforming. I'm not sure we want to tell authors 
what the error handling behaviour is when they ignore the conformance 
requirements... do we?


> 4.6.3.2
> -------
> Section 4.6.3.1 says that the initial "CACHE MANIFEST" line may have zero or
> more trailing space or tab characters, but step 9 of the parsing algorithm
> says that trailing whitespace is disallowed.

Fixed.


> Step 19: Beneath 'If mode is "fallback"', there are two places where the 
> phrase "opportunistic caching namespaces" is used. In both cases, 
> "namespaces" should be replaced with "namespace".

Fixed.


> Step 19 should specify what the user agent's behavior should be when an 
> explicit or fallback URI is encountered which was already encountered in 
> an online whitelist section, or when an online whitelist URI is 
> encountered that was already encountered in an explicit or fallback 
> section.

I've added a note below the algorithm about this.


> Step 21 of the parsing algorithm should end with "and the online 
> whitelist URIs" instead of "and the online URIs".

Fixed.


> 4.6.4
> -----
> Steps 8.2 and 19.3.2 say that the user agent should "discard cache". What does
> "discard cache" mean (in the case of an upgrade attempt, "cache" is a possibly
> in-use cache)?

The "discard cache" step is never reached when "cache" is in use. Is the 
meaning really ambiguous? I'm not sure how else to say it.


> In step 19.3.2, what is to be done with "new cache"?

(Now step 20.3.2.) In this step, "new cache" and "cache" are the same.



> Step 19 should specify what should happen if a URI that is already in the
> cache's online whitelist is to be added as an explicit, fallback, or dynamic
> entry.

(Now step 20.) It does. Which is to say, it being on the online whitelist 
has no effect. Should it have an effect? We can omit the caching of such 
files if you want.


> Step 22 should specify what should happen if a URI that is already in 
> the cache as an explicit, fallback, or dynamic entry is to be added to 
> the cache's online whitelist.

(Now step 23.) Nothing special happens. What would you have happen?


> It would be good to make it clear in steps 19.{5,6,7,8} that an entry 
> can end up in multiple categories.

(Now steps 20.{5,6,7,8,9}.) Clarified with a note.


> 4.6.5.1
> -------
> What happens if the resource's URI is a javascript: URI? This seems
> particularly interesting in the case of fallback URIs.

It can't happen anymore. Such URIs are ignored.


> 4.6.6
> -----
> Small typo in the description of the length attribute: "and zero the object is
> not associated..." should have the word "if" between "zero" and "the".

Fixed.


> The description of the length attribute says "The length attribute must 
> return the number of entries in the application cache...", but should I 
> think say "The length attribute must return the number of _dynamic_ 
> entries in the application cache..." to be consistent with subsequent 
> paragraphs.

Fixed.


> What happens if you add() a URI that is in the online whitelist?

Nothing special. It gets added, but you can't access that entry.


> Should an exception be thrown if remove() is called with a URI that is 
> not a dynamic entry?

Given that add() can fail to add without throwing, I'd rather not. But I'm 
open to changing that if people think it'd be better API design.


> In the definition of swapCache(), the Note in step 2 is unclear when it 
> says "this can only happen if...", as "this" could be interpreted as 
> either "success" or "abortion". I believe "success" is the correct 
> interpretation, but it would be nice to be clearer here.

Clarified.

-- 
Ian Hickson               U+1047E                )\._.,--....,'``.    fL
http://ln.hixie.ch/       U+263A                /,   _.. \   _\  ;`._ ,.
Things that are impossible just take longer.   `._.-(,_..'--(,_..'`-.;.'