comments on Packaging and Configuration specification

Hi,
Here are a few comments on the 4 March version of the editor's draft:

*Abstract

"This document standardizes a general packaging format for applications."
-> just "applications"? Not web applications, or sofware applications, or something less vague?

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

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

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

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

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

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

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

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

1.6
"Global definitions"
-> just "Definitions"?

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

"A language tag is a string that matches the syntax, and expected usage, of Language-Tag as defined"
-> "text string". But maybe I'm nitpicking, but you say text string later in the spec.
-> "expected usage of _a_ Language-Tag" or plural? or just "language tags". 
-> 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..."

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

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

"Products that generate widget resources and/or allow authoring of configuration documents must not claim conformance to this specification"
-> 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: "Products must not claim conformance to this specification, in order to claim conformance to this specification" :)

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


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

"[ZIP], but with the exclusions listed in the Zip support section."
-> "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."
22 -> Deflate is not part of Zip?

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

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."
-> [ZIP] -> "(as defined in [ZIP])"
-> generally, for terms defined in ZIP I would not make them bold like terms defined in this specification, I would italicize them, for instance.

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

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

"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."
-> why is "valid compression method" brown with a border?
-> "as" -> "is"?
->I would format Notes in a less strong type. If they're not normative, they should not big green, bold  and italic.

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

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

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

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

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

6.1
"...non-conforming to this specification in such a way that."
->unfinished sentence
->same as above for "Note:" prefix missing

6.2

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

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

"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.
-> "MIME type" doesn't exist as such. RFC2045 uses media type.

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

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

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

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

"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

6.8
"However, a user agent must not execute scripts or interactivity defined within and [SVG] icon file"
->"and" -> "an"
-> I don't understand what "This" in the next sentence refers to.
-> why is the next paragraph surrounded in red, and says "you"? Unfinished, I suppose.
"must not rely upon script"
-> "rely" is a vague term, especially after a "must not", although I can't find a better wording.
19 -> you use "warn" several times. Do yo mean "inform"? 
20 -> throughout the spec, file name is sometimes written filename

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

7 
-> "constancy" -> "consistency"
"The following is an example of a config.xml document:"
-> "... an example of a configuration document."
-> "http://datadriven.com.au/exampleWidget" The W3C police will ask you to use example.org at some point ;) also elsewhere
See "Step 7 for instructions on how to process a configuration document.
-> one " too many

7.1
"The widget namespace is http://www.w3.org/ns/widgets"
-> "The widget namespace URI is http://..."
"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."

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.
"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"
"consists of one of more characters in the range"
-> "code point"
"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..."
"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..."
-> what does "the term is used" mean?
"URI attribute"
-> I would make the tokens (URI and IRI) in monospace orange, like the tokens above.
"influence on child elements that are XML text content"
-> "influence on the contents and attribute values of child elements" (reusing the phrasing in [XML])
"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.
-> last sentence in that example: "you" -> "authors"

7.4
"preference: zero or more."
-> link missing
" A valid URI that denotes a identifier for the widget."
-> "an identifier"
"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.

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

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

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

7.9
-> what happens if there's more than 1 icon element? (same goes for previous element definitions, in fact)
-> you don't use the Numeric type attribute definition? instead you link to "valid non-negative integer". 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.
->"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>
->" If the file pointed to by the src is a " -> pointed to by the src attribute (twice)

7.14

-> "persistantly" -> persistently
-> "these values are runtime." -> "at runtime"
-> why is it "should not"? Sounds like it should be a "must not".
-> "A boolean attribute wether this preference can be overwritten at runtime." -> "A boolean attribute indicating whether this preference can be overwritten at runtime."
-> "<widgets xmlns="http://www.w3.org/ns/widgets">" -> widgetS
-> section is missing subsections "Context in which this element is used", etc.

7.16
-> in the example the rtl characters are "?"
-> 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".

8
->starting note. It contradicts the first "must" in the following paragraph, especially on the order of operations.
->"and may inform the end-user with an appropriate localized error message" I suppose you want to make "inform" bold.
->"(see example in the note below)" Can't see an example in a note below. Should be "example below"
->"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".
-> 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.

Step 1
-> "would not" in bold?
->" "The rules for determining if a potential Zip archive is a Zip archive is as follows." -> "are as follows"
-> the 2 paragraphs that follow that statement should be a <ul>
-> "With the Zip archive, the user agent must verify the Zip archive" not sure what it means.

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"?
->"then a user agent must treat the Zip archive is an invalid widget:" -> as an invalid widget
->"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 shoudl be just italic, tho)
-> a digitally signed widget is invalid?
23 -> "A user agent must now set the configuration defaults (step 3)." now->then

Step 3
-> "user agents" -> Capitalise U
-> start file encoding is ISO8859-1? Think you can get away with it?
-> many parameters of type DOMString have null as their initial value. Is that the string "null", or just null?
-> "the user's most preferred" just "preferred".
-> "English Ausralia" you mean "US English"
 
step 4
->"The algorithm to locate digital signatures is lac" ...?

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"?
"repeat number 2" -> repeat step 2?

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

step 8
->"config doc" is normally called "widget config doc" (and should be "configuration document", to conform to the definition)
->It is never actually said that in order to be correct, a configuration document must be a valid configuration document
->"The term in error is typically used to mean" -> typically?
->"Typically the specification will say that the erroneous" -> ditto
->" (any Node with node type 3 or 4)" I think you should use "type TEXT_NODE or CDATA_SECTION_NODE" instead.
->"occurrence of the xml:lang attribute" -> type xml:lang with markup style.
->"it is a widget element:" in bold? And you should expand "it"
->"ISSUE: what if xml:base was declared?" is that related to width and height?
->"starting from the first moving to the last in tree order" -> what's tree order? document order?
->"then let widget start file to be that matching file entry" -> "then let widget start file be that matching file entry"
->"concatination"
->"resouce"
->"If file entry pointed to by the potential start file path" -> file entry shoudl be a link and preceded by "the"
->"check if the is a file entry"
->"value of the src attribute" -> mark up "src" (twice)
->"relative to the root of the widgets" -> widget
->"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]."
->in "Rules for Getting Text Content", the result variable is never used.
->same section, 3. there's a. but no other item.
->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>

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

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



Max.

Received on Monday, 9 March 2009 10:26:06 UTC