Re: 3.6. The root element

On Jul 31, 2007, at 4:04 AM, Anne van Kesteren wrote:

>
> On Mon, 30 Jul 2007 19:37:00 +0200, Robert Burns <rob@robburns.com>  
> wrote:
>> I think the problem Ben is pointing out is that the last three  
>> paragraphs of the root element subsection (one normative paragraph  
>> and the two "green" notes are very unclear. (for authors and UAs).  
>> I think those should be rewritten into a single coherent paragraph  
>> that addresses the attribute names "xmlns" or "xmlns:*".
>
> It seems you're misunderstanding what this is about as well. The  
> draft points out that for _HTML documents_ (solely text/html) the  
> HTML element may have an attribute xmlns specified that has the  
> literal value http://www.w3.org/1999/xhtml. The note then goes on  
> to point out that this xmlns attribute, when specified, is  
> different from the identically named attribute in the XML  
> serialization.

It may very well be that I'm misunderstanding the current draft.  
However, you're missing the point of my email message. It is entirely  
unhelpful to simply point out that a reviewer is misunderstanding the  
draft. I t would be much more useful to the work of this WG to try to  
intervene with an email reply that starts to make sense of that  
misunderstanding and help find a way to improve the draft. As it  
stands now, the entire section (except the first sentence) reads  
mostly like an overly pedantic discussion about the @xmlns attribute.  
It fails to provide enough information for either authors or UA  
developers to know what they're supposed to do with this attribute  
(it also fails to explain this in a way that acknowledges the two  
possible serializations).

For example, calling it a talisman in the first note forgets that we  
have two serializations. If the point is merely to allow authors to  
include the namespace for XML serialization compatibility, then why  
not say that. That would make it clearer to authors and UA developers  
alike. It might also be worth saying that this namespace declaration  
for HTML must be the default namespace declaration for the document  
in the text/html serialization. It might also be worth mentioning  
that other attributes in the xmlns namespace may be added to text/ 
html document, but they too will be ignored (if we're trying to  
create compatibility between the two serializations).

> It would be nice of course if everyone reading the draft would  
> understand this immediately and if there are suggestions that would  
> enable that I'm sure the editor would consider them.

Well what can we do to improve that? We should redraft all three  
paragraphs (the normative paragraph and the two "green" notes) to  
clearly explain what authors and UAs should do with xmlns related  
attributes in either serialization or when they get added through DOM.

> Personally I'm not really sure how it can be made more clear.

You shouldn't feel obligated to reply to every email. If you don't  
have something constructive to contribute, don't worry about it.

>> Instead of just not requiring those attributes, we could also  
>> require those attributes have author specified values. We could  
>> give advice to authoring UAs that they should retrieve the values  
>> from these either from their own preferences or from the system  
>> preferences for the author. Every author has a primary language  
>> set in their operating environment or in their authoring tool  
>> environment. That language has a directionality. Those attributes  
>> can easily be set from that information. Providing a dialog on  
>> "new" can also help the author change those values on a case-by- 
>> case basis.
>
> That is exactly why we should not do this. Most things I write are  
> either in Dutch or English. If some editor picked my system  
> preferences I would always write in English. (In case the  
> suggestion comes up, I'm not switching the language of the spell  
> checker (if enabled at all) each time I write something.)

As I said "from their own preferences or from the system  
preferences".  This means that an application could retrieve it from  
its own preferences where you would indicate a specific language or  
indicate you want to be queried about this whenever you create a new  
document (or open/save an existing document without a root value  
set). The application could even provide a selection of just two or  
three or n languages indicating just the languages you might ever  
want to set for a document.

>>> Specifications are meant to cover the nasty little details. If a  
>>> specification were just an authoring guide it wouldn't be of much  
>>> use to picky authors who'd like to know how things are actually  
>>> working. You'd just have another HTML 4.
>>
>> Certainly, specifications cover the nasty details. However those  
>> details can be covered from multiple perspective. Right now the  
>> draft only presents those nasty details from the UA perspective  
>> and not the author perspective. We should not shy away from  
>> presenting both perspective.
>
> Actually, what was discussed at the top of this e-mail (and what I  
> was referring to) is an authoring detail.

It may be only an authoring detail. However, it is not written in a  
clear manner that an author would understand when and where to use  
this attribute (and when not to use this attribute) and what effect  
this attribute would have when setting it.

>> For example, in the microsyntaxes section the current draft  
>> explains to a UA how to parse out various data types given a  
>> string. We should also provide normative language for authors to  
>> create such a string that will contain the authors intended data  
>> types. This doesn't have to be written in less detail.
>
> The draft does define what constitues a valid time string for  
> instance in as much detail as how the UA has to parse them as it  
> uses the same algorithm to do so. I suppose tutorials or maybe an  
> introductory section in the specification can make this easier to  
> comprehend.

As I said, independent of other non-normative documents, our  
recommendation should indicate to authors precisely how they should  
write a real number or ratio or boolean without needing to read the  
parsing algorithm. That's there for boolean perhaps, but in many  
cases, the current draft does not provide these author-centric  
normative explanations.

Take care,
Rob

Received on Tuesday, 31 July 2007 09:34:19 UTC