Re: [XBL Primer] Comments

Hi Jose,

On 4/4/07, José Manuel Cantera Fonseca <jmcf@tid.es> wrote:
>
>  Commenting:
> http://dev.w3.org/cvsweb/2006/waf/XBLPrimer/Overview.src.html?rev=1.16
>
>  + There are some typos in the document
>
>  + Abstract
>
>  "This document provides you with the practical knowledge ..."
>
>  Shouldn't it say "This document provides the practical knowledge ..."
> Perhaps for you native speakers it sounds ok but for me no, I don't know ...

To me it reads ok. It's just written in an informal voice; that's
intentional. If we find that people find this style irritating, then
we can change the tone.

>  + Status of document
>
>  "Implementors should be aware that this specification is not stable ...
>  "This document was produced ...
>
>  Is this really needed for a W3C Note? This is not the XBL 2 spec ....

It might not look like it now, but this ain't no W3C Note; It's going
down the rec track. This was agreed to at the last face to face
meeting in Boston. There is precedence for this (xml schema, rdf,
etc).

>  + Table of contents
>  It would be good to have it completed, although some of the contents were
> empty. This would give the reader an overview of the whole document and what
> the editors are planning to do for the next versions

Agreed. We will have a better idea after the next face 2 face meeting
(April 17th)... also I need to run the CSS processor over the document
to get the proper ToC. However, I won't process it until the document
is much more mature because the processor makes a mess.

>  + Use of the word XBL. It should be used consistently over the whole
> document i.e. it should be used XBL 2 everytime or there should be a
> statement saying that "hereinafter when the 'XBL' word is appearing we are
> talking about 'XBL 2'"

Agreed. I will change everything to "XBL".

>  + Introduction
>  Perhaps the statement "The move in web development towards avoiding the
> table element for layout has led developers to consider how to exploit other
> HTML elements, CSS, and ECMAScript to achieve complex layouts." should not
> be the first in this paragraph and should be used as an example of highly
> accessible content i.e avoiding usage of tables for layout

I don't understand. Can you please elaborate?

>  + XBL concepts
>  The content under this section hasn't any concepts ...

:-)

>  + Working example.
>
>  In the text it is mentioned "Log on· as legend, but in the markup example
> appears "Log in" in the legend tag. In the next step (adding divs and CSS)
> in the figure appears login instead of log on :)

Yes, I have to take another screen-shot of the image. It's on my todo list.

>  You don't have put a label for the submit input, this occasionates that a
> default label is put in the submit button and that label depends on the
> browser language, so in my browser, which is configured in Spanish, I see a
> Spanish label intermixed with the English labels of the other fields.

Ah, of course! I will fix that. I should get into the practice of
putting my system language into Spanish to test stuff.

>  In the div example the CSS is not shown. This can be misleading

Still working that out.

>  I don't see the need of duplicating the effort creating one XML version and
> another HTML version of the example. One practical way to face this
> difference would be to work in XHTML (the more general option) and provide
> an specific example wrt attaching the XBL via CSS (which is also permitted
> in XHTML) and say "this is the way how an HTML document would be bound to an
> XBL binding"

Yeah, I figured that too... I will dump the XHTML examples and only do
HTML. When I first wrote this, I thought XHTML still had a future;-)

>  + Creating an XBL document and attaching it to another document
>
>  It seems that this section looses the continuity with the example,
> shouldn't be the continuation of the example?

Yes, I agree the linking is very weak here. I will fix that soon, but
the current example my be dumped because I am starting to think that
XBL adds little value to it.

>  + Attaching XBL using ...
>
>  I'm missing the example of attaching XBL by means of CSS

We will add that into the example.

>  The example stops "violently", why the first example is not completed with
> the actual binding used to resolve the problem?

I think there is a note there about that in the document. However,
that example may be dropped.

>  + Recap of terminology
>
>  Shouldn't it be in chapter 1? under the concepts section?

Those sections will be similar to each other. Some people might not
want to read the tutorial in chapter 1 and might just want to jump to
the more advanced examples in part 2...

>  + The <xbl> element
>
>  "XBL elements that are not inside an XBL declaration are treated as
> arbitrary XML, even is the elements are scoped through a namespace" What are
> you trying to mean? Does it make sense to have XBL elements outside an XBL
> declaration?. if it is an obscure feature it shouldn't be mentioned in a
> primer

I will clarify this in the primer a bit... however, it means that you
can't do the following:
<widget xmlns="http://e.com/ui"
        xmlns:html="http://www.w3.org/1999/xhtml"
	xmlns:xbl="http://www.w3.org/ns/xbl">
   <xbl:script>
   	alert("this will never work..");
   </xbl:script>
   <html:script>
   	alert("but this will!");
   </html:script>
</widget>

>  + The content element
>
>  The examples are not read properly. They are confusing. The purpose of the
> example, the problem to solve and the binding used is not explained clearly

Yes, this section is fairly poor ATM.

>  + Rest of the document. Examples are missing

Lachlan Hunt has just joined the working group to help us come up with
good examples.

>  Could it make sense to have a complete example, use case that illustrates
> the usage of the prefetch, resources, style, etc, at the same time?

We can definitely have that. Please send us more requests or send us
usage examples.

Thanks for the comments!

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

Received on Thursday, 5 April 2007 00:55:02 UTC