Re: comments on Packaging and Configuration specification

Hi Max,
On Mon, Mar 9, 2009 at 11:25 AM, Max Froumentin <maxfro@opera.com> wrote:
> Hi,
> Here are a few comments on the 4 March version of the editor's draft:
>
> "This document standardizes a general packaging format for applications."
> 1->  just "applications"? Not web applications, or sofware applications, or something less vague?

went with software

> "This document standardizes a general packaging format for applications. The specification relies on PKWare's Zip as the packaging format"
> 2->  that somehow sounds contradictory. I would perhaps change the second "packaging" to "archive" or "container".

went with archive.

> 3->  I know that user agents is the official term, but in this case I would use the more obvious "execution environment" or "runtime",
> or "client machines" as used in the introduction.

runtimes it is.

>
> 4->Mention that widget is a special case of web application, as soon as widgets is first used. And somehow convey that any mention of widget in the text applies to general web applications.

I added "Widgets are client-side applications that are authored using
Web standards, but whose content can also be embedded into Web
documents" into the abstract.

> "The configuration document is an XML vocabulary that authors can use to declare metadata"
> 5->  "The configuration document is an XML vocabulary that declares metadata"

done.

> "This document also defines conformance criteria [to verify] that Zip archives and configuration documents conform to this specification."
> 6->  a bit tautaulogical :)

removed "conformance criteria and", hopefully less tautological.

> 1.3
> 7->  Why is localized folder not called locale folder?

Fixed globally.

> "The second half, which starts in the section ..."
> 8->  starts with?

fixed

>   "erroneous [DOM3Core] nodes"
> 9->  not sure what that means

Changed [DOM3Core] nodes > DOM nodes. Better?

> 1.4
> 10->  I assume 1.4 is a joke, and will be removed?

Nope.

> 1.6
>
> (I like that section very much, I have to say. Much nicer than a boring glossary ;)
>
> "Global definitions"
> 11->  just "Definitions"?

Fixed

> "An author is a person who creates a widget resource or an authoring tool that generates widget resources."
> 12->  so if I use a tool to generate a widget, who's the author? Me or the author of the tool I used?

The tool... or both... does it matter?

> "A language tag is a string that matches the syntax, and expected usage, of Language-Tag as defined"
> 13->  "text string". But maybe I'm nitpicking, but you say text string later in the spec.

Added "text"

> 14->  "expected usage of _a_ Language-Tag" or plural? or just "language tags".

added "a".

> 15->  I would drop the periods, but add one after language-Tag, but maybe I'm very nitpicking
>"A language tag is a text string that matches the syntax and expected
usage of language tags, as defined..."

Ok. Used your text.

> "Because widgets are packaged, they can be liberally shared by users"
> 16->  "liberally"? Freely, rather? Or nothing.

Dropped "liberally"

> 2
> "relevant to authors and authoring tool implementers"
> 17->  given your definition of author, both are the same

Right. Dropped "and authoring tool implementers"

> "Products that generate widget resources and/or allow authoring of configuration documents must not claim conformance to this specification"
> 18->  I love the logical conundrum! Given that RFC2119's "must" really means "must ... in order to conform to this spec",
> your use of "must  not" means you use conformance to this spec in order to define non-conformance to the spec!
> As if you'd written: "Producs must not claim conformance to this specification, in order to claim conformance to this specification" :)

Hehe. gone. FWIW, Josh also pointed out that the above was kinda broken.

> 19->  "Authoring tools and markup generators must generate conforming configuration documents and/or widget resources."
> Somehow means to me "authoring tools must generate conforming stuff to conform to this specification"

Also removed.

>
> 3.1
> "In addition to this specification, a user agent must support the following specifications and file formats:"
> 20->remove "In addition to this specification". It's redundant.

Done.

> "[ZIP], but with the exclusions listed in the Zip support section."
> 21->  "with the exclusions" could be misinterpreted. I'd prefer "The mandatory features of [ZIP], as defined below", even though it's not great either. Unless you change 3.3 to say: a user agent must support all of zip, except: ... which is optional."

Fixed.

> 22 ->  Deflate is not part of Zip?

Yes and no. The algorithm is defined elsewhere.

> 4.
> 23->It's confusing that "inform" is in bold. Because we're not in a definitions section, it's not obvious that the paragraph defines what inform means. Couldn't it go in the definitions section, or rephrased to something like "informing means..."

I see what you mean, but, as stated in the Definition section, lots of
definitions are given throughout the document. I would prefer to leave
this one as is.

> 5.
> "A file entry is the data held by a local file header, file data, and (optional) data descriptor [ZIP] for each physical file stored in a Zip archive."
> 24->  [ZIP] ->  "(as defined in [ZIP])"

Fixed.

> 25->  generally, for terms defined in ZIP I would not make them bold like terms defined in this specification, I would italicize them, for instance.

Done. All definitions external to the document are now italicized.

> 5.1
> "Note: Not using the valid compression methods will result in the user agent treating the widget as an invalid widget."
> 26->sounds like it should be a normative statement, not a note.

Removed the note.

> "it should inform the author that file entry should be recompressed the files of the widget resource with [Deflate]."
> 27->  grammar seems wrong

Removed "the files of the widget resource".

> "If a CC encounters a compression method that is not a valid compression method, it must inform the author that the resource as an invalid widget."
> 28->  why is "valid compression method" brown with a border?

fixed.

> 29->  "as" ->  "is"?

fixed.

> 30->I would format Notes in a less strong type. If they're not normative, they should not big green, bold  and italic.

Added a new style for notes.

> "a user agent must be prepared to deal with path lengths longer than 250 bytes"
> 31->  "prepared" ->  "able"

fixed.

> "A CC must inform the ..." (and many times in the doc)
> 32->  "inform" should be a link to its definition

Fixed globally.

> 5.4
> "Unicode Character", or "U+0020 SPACE character" etc., a few times throughout the spec
> 33->  "Unicode Code Point"

fixed.

> 6.
> "Zero or more screenshot,"
> -> missing 's'

Fixed.

> "See step 1 - Acquire a Potential Zip Archive for instructions on how to process a widget resource."
> -> not prefixed with "Note:" like other notes.

Fixed.

> 6.1
> "...non-conforming to this specification in such a way that."
> ->unfinished sentence

fixed. added "...it would not be possible for the user agent to
continue processing."

> ->same as above for "Note:" prefix missing

fixed.

> 6.2
>
> "6.2 Files and Content Types"
> ->why in bold?

fixed.

> "files within a Zip archive [are not] dynamically generated at runtime."
> ->what does it mean to generate the files? Could it be conceivable that the "files" are decompressed in memory at runtime?
>

This was meant in the CGI-sense, where a resource is generated upon
retrieval. Sentence now reads:
"nor are files dynamically generated from query parameters when the
use agent retrieves them from within a zip archive."

> "a user agent must use file extension to MIME mapping followed by content-type sniffing to determine the MIME type of a file."
> -> I would rewrite as "a user agent must preform file-extension-to-MIME mapping, followed by content-type sniffing, in order to determine the MIME type of a file.
>

Used your text.

> -> "MIME type" doesn't exist as such. RFC2045 uses media type.
>

Fixed globally.

> "the last character of the file name field [ZIP] is a U+002F SOLIDUS"
> -> The use of [ZIP] is a bit confusing to parse that sentence. Could you put it where you actually define "file name field"?
>

Yep, done.

>  "File names must be treated as case insensitive."
> -> because "case insensitive" is in bold italics, it looks like a definition. why not just normal text? Or link to whatever unicode defines as case?
>

fixed all instances. I agree that these are legible enough.

> "Note: user agents are not requred to support any of the MIME types listed in the default start files table."
> -> requred->required

fixed.

> -> why in a note? sounds normative

Made it normative:
"It is optional for user agents to support any of the media types
listed in the default start files table"

> "See step 9 for instructions for finding a default start file."
> -> I prefer "instructions on finding"

fixed.

> "Author requirements: Always include at least one start file in a widget resource."
> -> what's an author requirement? How does it relate to the conformance of the spec? Also, it's not consistent with the singular and plural of requirements
>

Changed all "author requirements" to "authoring guidelines". I added
the following to the conformance section: "As well as sections marked
as non-normative, authoring guidelines... are non-normative"

>
> 6.8
> "However, a user agent must not execute scripts or interactivity defined within and [SVG] icon file"
> ->"and" -> "an"

fixed.

> -> I don't understand what "This" in the next sentence refers to.

Changed "this" -> "Animation and interactivity".

> -> why is the next paragraph surrounded in red, and says "you"? Unfinished, I suppose.

Yes, this is unfinished. I will finish it soon... it's just a reminder
note. I've changed the styling.

> "must not rely upon script"
> -> "rely" is a vague term, especially after a "must not", although I can't find a better wording.

Changed it to "Authors using [SVG] as an icon format should create
icons that use declarative animation, and must not make icons
exclusively dependent on scripts for animation and interactivity." Not
sure if it any better?

> 19 -> you use "warn" several times. Do yo mean "inform"?

Changed all instances of warn to inform, and linked to def.

> 20 -> throughout the spec, file name is sometimes written filename

Fixed globally.

> 6.10
> "Note: user agents can support other legacy/proprietary widget types, but they must remain conforming to this specification when dealing with widget resources."
> -> again, "must" in a note, confusing :) I'd rather "Note: user agents can support other legacy/proprietary widget types, on top of the types required by this specification"
>

That is a testable assertion, so put it back into the spec under the
Conformance section. It now reads:

"User agents may support other legacy/proprietary widget types, but
must conform to this specification when dealing with a widget
resource."

> 6.11
> -> I would avoid "my." in examples of case forms. Someone could infer from the examples that myw.gt is valid. Why not just .wgt, .Wgt, .WgT, etc. ?
>

fixed. removed all "my".

> 7
> -> "constancy" -> "consistency"

fixed

> "The following is an example of a config.xml document:"
> -> "... an example of a configuration document."

Fixed.

> -> "http://datadriven.com.au/exampleWidget" The W3C police will ask you to use example.org at some point ;) also elsewhere
>

Argh! I can't work under this totalitarian regime that suppresses my
PageRank!:) Fixed globally.

> See "Step 7 for instructions on how to process a configuration document.
> -> one " too many

Fixed.

> 7.1
> "The widget namespace is http://www.w3.org/ns/widgets"
> -> "The widget namespace URI is http://..."

Fixed.

> "Authors should be aware that, if the namespace is absent then Zip archive will be treated as an invalid widget."
> -> suggest "If the widget namespace declaration is absent, then the Zip archive must be treated as an invalid widget."
>

Author guidelines are just warning to authors: your suggestion implies
that the author must treat it as an invalid archive (which is kinda
correct, but not really). The UA treating the widget as invalid
happens later in the doc.

> 7.3
> titles: "Version attribute", "Numeric attribute"
> -> I would add "type" at the end of each title, to avoid confusion between the actual attributes and the types defined.
>

Done.

> "An attribute defined as containing string or is empty."
> -> a bit unclear. How about "a version attribute type is an arbitrary string (possibly empty) that indicates the version of the widget. This specification does not mandate any specific format or processing rules regarding the format of this attribute type, but it is recommended that it conforms to the following ABNF... Note: this may change in future versions"
>

I like it! included, but with some minor modifications. I abstracted
your definition, just in case other aspects require version numbers in
the future.

> "consists of one of more characters in the range"
> -> "code point"

fixed

> "An attribute defined as requiring a certain string value (e.g. apple or orange)."
> -> suggest "A string which is one of a finite set specified in the attribute's definition. The possible values must be speficied exactly..."
>

Added.

> "How a user agent is supposed to interpret a boolean attribute is described when the term is used."
> -> The way a user agent interprets a boolean attribute..."

Fixed.

> -> what does "the term is used" mean?

Changed it to:
"The way a user agent interprets a boolean attribute is specified in
the attribute's definition."

> "URI attribute"
> -> I would make the tokens (URI and IRI) in monospace orange, like the tokens above.

done.

> "influence on child elements that are XML text content"
> -> "influence on the contents and attribute values of child elements" (reusing the phrasing in [XML])

Fixed.

> "The intended purpose..."
> -> that paragraph has a bar to the left that leads to think that it is an example. However the content doesn't seem to be just that.
>

Right, I folded the text into the authoring guideline.

> -> last sentence in that example: "you" -> "authors"

Fixed.

> 7.4
> "preference: zero or more."
> -> link missing

Fixed.

> " A valid URI that denotes a identifier for the widget."
> -> "an identifier"

Fixed.

> "the user agent will assume the value 300."
> -> "must". I'm rather ambivalent on trying to use must as much as possible. On the one hand you could have it on most statements in the specification, rendering it unreadable. On the other, it may seem arbitrary to use it in some places and not in others. e.g. ideally the previous sentence should use it as "height must be a valid non-negative integer greater than 0 and must control the initial height dimensions of the instantiated start file in CSS pixels [CSS21].". The must/may/should RFC might give answers on this.
>

What you describe happens during processing. The first half of the
document is concerned with defining things, the second half deals with
constraints and machine testable conformance. If I start mixing
processing then we don't need the Steps. It was a editorial decision
to split the two so to avoid duplication (even if there is duplication
in the intent of the sentence).

> 7.5
> ->You should perhaps have a precise definition of the contents of the element. Because "human-readable" might be seen as contradicting "Content model: any": if it's got markup in it, it's hardly human readable. Same for 7.6
>

Understood, I added ", after processing via Step 7," so after
processing whatever any other elements go in there, the end result
should be understood by humans.

> "Usage Example: This section is non-normative."
> -> you've already said that examples are non-normative. also in 7.6, 7.7 etc.

Fixed all examples. Styled all description of examples with double
bars so it clear that the text is not normative.

> 7.7
> -> no more mention of human-readable? also 7.8 etc.

As above.

> 7.8
> -> why does the href attribute has a link to href in 7.12?

Will fix this in CR.

> 7.9
> -> what happens if there's more than 1 icon element? (same goes for previous element definitions, in fact)
>

This is defined in Step 7 and relates to processing.

> -> you don't use the Numeric type attribute definition? instead you link to "valid non-negative integer".

fixed.

> In fact you do it many times, e.g. the definition of xml:lang in <widget> should refer to
>"xml:lang attribute" in 7.3. Otherwise 7.3 is not really useful.

Right. fixed globally.

> ->"ISSUE: what if it's a vector and no size is given?" I'd say implementation-dependent given the possible sizes of screens, but then it should be the same for width and height on <widget>
>

Right. Removed the issue and will deal with it appropriately if it
comes up again.

> ->" If the file pointed to by the src is a " -> pointed to by the src attribute (twice)
>

fixed.

> 7.14
>
> -> "persistantly" -> persistently

fixed

> -> "these values are runtime." -> "at runtime"

fixed

> -> why is it "should not"? Sounds like it should be a "must not".

Agreed. fixed.

> -> "A boolean attribute whether this preference can be overwritten at runtime." -> "A boolean attribute indicating whether this preference can be overwritten at runtime."
>

fixed

> -> "<widgets xmlns="http://www.w3.org/ns/widgets">" -> widgetS
fixed

> -> section is missing subsections "Context in which this element is used", etc.

added.

> 7.16
> -> in the example the rtl characters are "?"

Argh! all my foreign text has disappeared! :( I'll fix that before we
republish.

> -> like 6.
> -> "The its:dir attribute and the <its:span> element can be used as a child of the following elements of the configuration document:" -> "can both be used as children", or "can each be used as a child".
>

went with: "can each be used as a child"

> 8
> ->starting note. It contradicts the first "must" in the following paragraph, especially on the order of operations.
>

Yeah, I see what you mean... that's why we say "so long as the end
result is indistinguishable from the result that would be obtained by
following the specification."

> ->"and may inform the end-user with an appropriate localized error message" I suppose you want to make "inform" bold.
>

Made it link to def.

> ->"(see example in the note below)" Can't see an example in a note below. Should be "example below"
>

Deleted.

> ->"The wording of an appropriate localized error message is left to the discretion of implementers; however, their presence is nonetheless recommended." should be "its presence".

fixed.

> -> Not sure what the purpose of the error message example is. I think it's a bad error message, too. Users wouldn't care about knowing that's it's about an unsupported compression method.
>

Ok, deleted.

> Step 1
> -> "would not" in bold?

fixed

> ->" "The rules for determining if a potential Zip archive is a Zip archive is as follows." -> "are as follows"
>

fixed

> -> the 2 paragraphs that follow that statement should be a <ul>

Fixed.

> -> "With the Zip archive, the user agent must verify the Zip archive" not sure what it means.

Deleted. Made changes in step one so that if the magic numbers are
successfully matches, the UA is instructed to proceed to Step 2.

> Step 2
> -> "If any of the following conditions occur/apply (indicating that a condition is met)" -> why not just "if any of the following conditions are met"?

Fixed.

> ->"then a user agent must treat the Zip archive is an invalid widget:" -> as an invalid widget

fixed.

> ->"which is denoted by general purpose bit 0 being set" -> "which is denoted by bit 0 of the general purpose field being set" with "general  purpose field" in bold, like "archive decryption header" and "archive extra data record" (IMO should be just italic, tho)
>

I've made them all italics, and made it more clear that those terms
are defined in the Zip spec.

> -> a digitally signed widget is invalid?

It is invalid if it uses proprietary PKWare dig sigs, yes.

> 23 -> "A user agent must now set the configuration defaults (step 3)." now->then
>

fixed.

> Step 3
> -> "user agents" -> Capitalise U

fixed

> -> start file encoding is ISO8859-1? Think you can get away with it?

The i18n WG said we should use it. Problem?

> -> many parameters of type DOMString have null as their initial value. Is that the string "null", or just null?

Just null. I've added the following text:
When a null value is assigned to a variable in the Configuration
Defaults table, an implementation must treat the value as null (i.e.,
not as empty string and not as the text string "null").
is that ok?

> -> "the user's most preferred" just "preferred".

fixed.

> -> "English Australia" you mean "US English"

Woops! right. fixed.

> step 4
> ->"The algorithm to locate digital signatures is lac" ...?

Fixed.

> step 6
> ->"or contains a single '*', or is a sequence of items that only contain the '*' character" does that mean "is '*' or is a sequence of '*' items"?
>

changed it to "or contains a single '*', or is a sequence of '*'
characters (e.g. '*****'), then terminate this algorithm and go to
Step 6."

> "repeat number 2" -> repeat step 2?
>

I put repeat number to because I didn't want it to be confused with Step 2.

> step 7
> ->"within the zip archive" -> within the Zip archive?

Fixed.

> step 8
> ->"config doc" is normally called "widget config doc" (and should be "configuration document", to conform to the definition)
>

Right. This variable refers to the configuration default variable
"widget config doc". That variable will now be linked properly to its
definition.

> ->It is never actually said that in order to be correct, a configuration document must be a valid configuration document

There is no notion of validity, because erroneous and unknown DOM
nodes are ignored.
Is that ok?

> ->"The term in error is typically used to mean" -> typically?

Fixed (what? you use it to mean something different in casual conversation? ;) )

> ->"Typically the specification will say that the erroneous" -> ditto

Fixed (removed both instances).

> ->" (any Node with node type 3 or 4)" I think you should use "type TEXT_NODE or CDATA_SECTION_NODE" instead.
>

Fixed.

> ->"occurrence of the xml:lang attribute" -> type xml:lang with markup style.

Fixed.

> ->"it is a widget element:" in bold? And you should expand "it"

Fixed and fixed (expanded it to "the element"")

> ->"ISSUE: what if xml:base was declared?" is that related to width and height?

Nope. So I moved it to the start of the section

> ->"starting from the first moving to the last in tree order" -> what's tree order? document order?

Yes, document order. I have put a link to XPath which nicely defines
it. No one freak out! This does not constitute a dependency on XPATH,
only on the definition .

> ->"then let widget start file to be that matching file entry" -> "then let widget start file be that matching file entry"
>

fixed.

> ->"concatination"

fixed

> ->"resouce"

fixed.

> ->"If file entry pointed to by the potential start file path" -> file entry shoudl be a link and preceded by "the"
>

fixed

> ->"check if the is a file entry"

fixed

> ->"value of the src attribute" -> mark up "src" (twice)

fixed.

> ->"relative to the root of the widgets" -> widget

fixed

> ->"let start file encoding be the value UTF-8." -> "the" missing. Also UTF-8 links to bibliography but is missing the []. I would rewrite as "let the /start file encoding/ be <code>UTF-8</code>. Then the start file must be encoded as described in [UTF8]."
>

That's not quite right. All the UA is doing here is ascertaining if
the start file is, in fact, encoded as UTF-8. Your text seems to imply
that the UA must re-encode the file. I'll fix the broken link.

> ->in "Rules for Getting Text Content", the result variable is never used.

Deleted result var.

> ->same section, 3. there's a. but no other item.

Fixed.

> ->in "Rules for Identifying the MIME type of an Image", I don't think "required" is pointing to the right target.
> image/svg+xml should be in <code>

fixed.

> step 10
> ->"A user agent must search for a screenshot's file name based on the order they appear in the default screenshots table (from top to bottom)." -> A user agent must search for a screenshot file name based on the order they in which they appear in the default screenshots table (from top to bottom).

fixed.

> Appendix
> ->"Embedding a Widget Resource into an HTML Document" is not proper embedding, is it? More like referring to a widget resource.
>

Right. Fixed, Embedding is now Referring.

Whoa! Thanks Max for the detailed review!!! That totally fixed a
massive bunch of issues in the spec.

Kind regards,
Marcos
-- 
Marcos Caceres
http://datadriven.com.au

Received on Tuesday, 10 March 2009 14:28:14 UTC