Re: First Editors' draft of XML Stylesheet PI 2e

On Thu, 17 Sep 2009 18:15:54 +0200, Simon Pieters <simonp@opera.com> wrote:

>> Given that this is just a second edition of an existing spec,
>> why is the Abstract text so different?  Why can't the Abstract
>> text for the 2nd Ed be the same as that in the first?
>
> I agree.

Changed.


>> In section 3, under "the following conformance classes", why
>> is "Documents" a definition, but none of the other are?  I'm
>> generally confused by the structure of this section.
>
> I'm also a bit confused. It's different from how I wrote it (although my  
> text might also be confusing).

I've simplified it to just use user agents and authors, and updated the  
terminology throughout to be consistent. I also dropped requirements on  
other specs.


>> I'm finding the paragraph about user agents very fuzzy and
>> confusing.  What with xml parsers, a PIPA parser, an
>> xml-stylesheet processor, and browser/editor UA's, I have
>> no idea what "user agent" means and who is supposed to conform
>> to what.  I don't have a good suggestion--I'll need to think
>> more on this.

That paragraph is no longer there, although the requirements on user  
agents are all still just given as requirements on 'user agents'.


>> The only mention of conformance checkers is in the definition
>> of the conformance checkers conformance class.  I see no point
>> in having/mentioning the conformance checkers conformance class
>> at all.
>
> I guess we could strike the conformance class without affecting  
> conformance checkers who want to implement the spec. Conformance checker  
> implementors can probably figure out anyway what they need to implement.  
> Likewise with authors, authoring tools and markup generators.

Dropped conformance class for conformance checkers.


>> The last sentence of the last entry of section 3 reads
>>
>>  Such specifications must not modify the parsing rules defined
>>  in this specification.
>>
>> As an editorial suggestion to improve clarity, I'd say:
>>
>>  Such specifications must not modify the parsing rules defined
>>  in the _processing instructions with pseudo-attributes_ section
>>  of this specification.
>
> Indeed.

That was dropped, so is now moot.


>> What is marked as the definition of "processing instructions with
>> pseudo-attributes" isn't much of a definition.  Even extending
>> the definition to the rest of the paragraph (as suggested by
>> Simon) doesn't make it a definition.  This needs to be reworded.
>
> (My suggestion regarded the definition of "xml-stylesheet processing  
> instruction".)
>
> The intent is that other specs can say which PIs are PIPAs, or, in the  
> case of xml-stylesheet, section 5 says that "A processing instruction  
> that is a child of a document but does not appear after the element  
> child of the document and has the target xml-stylesheet is a processing  
> instruction with pseudo-attributes".
>
> I'm open to better wording suggestions.

I've recast the PIPA section into an "algorithm" that either returns a  
list of pseudo-attributes or an error, without giving requirements about  
ignoring the PI in the PIPA section. Instead the xml-stylesheet section is  
responsible of giving the requirements.


>> In the first para (defn of PIPA) of section 4, the last part
>> says "user agents must ignore the processing instruction."
>> See my comment above about user agents--I have a problem with
>> this.  In our issue document, we said that a PI that doesn't
>> match our PIPA syntax is not a PIPA, but we didn't say it
>> wasn't a PI, so it is not the case that all UAs must ignore it.
>
> Indeed, the intent is that it should be ignored for the purposes of  
> returning any pseudo-attributes.

The xml-stylesheet section now says to ignore the PI for the purposes of  
style sheet linking if parsing it returned an error.



>> In [3], the quoting is confusing.  I'm not sure what """ means.
>
> It should be "'" and '"'. Blame Henry. :-)

Fixed.


>> Perhaps it is supposed to be '"'.  Also, some forced line breaks
>> within that production might make it easier to eye-parse.  I'm
>> assuming it is supposed to be identical to production [3] in the
>> First Ed except for PICharRef in place of CharRef, but it's hard
>> to tell.
>
> Yes, I copy-pasted it from the first edition. We can insert line breaks  
> in the same places as the first edition.

Actually I don't know how to insert a line break there...

BTW I moved the exclusion of "?>" to the xml-stylesheet production,  
because the pseudo-attribute stuff is no longer necessecarily for PIs.



>> Re:
>>
>>  There must not be more than one pseudo-attribute with the
>>  same name in the content of any processing instruction with
>>  pseudo-attributes. If there are, user agents must ignore the
>>  processing instruction.
>>
>> (And the following para also ends with "the processing instruction
>> must be ignored".)
>>
>> As François pointed out, this paragraph is problematic, but mostly
>> because of my earlier issue with the "user agents" business.  Which
>> (part of the) user agent ignores what?  We should be saying that
>> such a PI is no longer considered a PIPA, but it is still a PI,
>> and who knows what other (part of some) user agent will be interested
>> in looking at it.  I'm still not sure how to fix this.

I've tried to fix this.


>> The first para of section 5 isn't readable. I suspect "document"
>> here means "infoset's [document] infoitem",
>
> Yes. What else would it be? The Terminology section says it's defined in  
> terms of infoset.
>
>
>> but if so, our decision
>> to omit the extra infoset-verbiage doesn't work for me.
>
> Ok. I guess we could add it, but it makes the spec less readable, IMHO.

Used infoset terminology now.


>> I also don't think this wording requires that the xml-stylesheet PI
>> is in the document entity.
>
> Indeed, that's intended.

Actually with the infoset there are no other places a PI could be, but  
with other XML APIs like the DOM, PIs could have no parent or be a child  
of a DocumentFragment, which is ok.


[snip]


>> Re:
>>
>>  Other pseudo-attributes must not be specified on xml-stylesheet
>>  processing instructions. User agents must ignore other  
>> pseudo-attributes.
>>
>> The first sentence isn't actionable--there is no subject for the
>> "must not", so it doesn't match any of our conformance classes

Fixed.


>> --and
>> contradicts the second:  how can a UA ignore something that isn't
>> there (and it can't be there if it "must not" be specified).  This
>> first sentence should be deleted.
>
> The first sentence applies to authors and validators. The second  
> sentence applies to user agents.

I hope this is clearer now.



>> Re productions [1] and [6], we had said (in the email thread referenced
>> from issue 15 in our issues document):
>>
>>  We didn't want to change production [1] because there may be references
>>  out there to it.  What we are trying to do is add a production for just
>>  the PI contents that can be referenced by specs that wish to do so  
>> without
>>  invalidating existing references to production [1].
>>
>> What happened with that idea?
>
> Indeed, I pointed this out also.

Fixed.


>> Also, what I see in the draft for productions [1] and [6] doesn't match
>> http://lists.w3.org/Archives/Public/public-xml-core-wg/2009Jul/0072
>> which is where I thought we were going.  I think what's in the current
>> draft is okay, but I'd like to hear the reasons for the differences
>> between that email's suggestions and the current draft?
>
> That was discussed in subsequent messages to the list. Production [1a]  
> in that email requires at least one pseudo-attribute, which the first  
> edition doesn't and specs using PIPA might want to allow an empty set of  
> pseudo-attributes.
>
>
>> ---
>>
>> Dump the Acknowledgments section
>
> Actually, I think it should be filled with the people who contributed to  
> the first edition and to http://simon.html5.org/specs/xml-stylesheet5

Done.

-- 
Simon Pieters
Opera Software

Received on Monday, 9 November 2009 08:29:52 UTC