Re: 3.1 Introduction (Draft), review of

On Jul 17, 2007, at 2:23 AM, Maciej Stachowiak wrote:

>
>
> On Jul 17, 2007, at 12:07 AM, Robert Burns wrote:
>
>>
>> Except in relation to chapter 3 we're talking independent of  
>> serialization.
>
> You can't give good authoring rules that are independent of  
> serialization, so I suggest we don't even try. Let's give authoring  
> guidelines for the HTML serialization and a separate section about  
> the XML serialization if called for. The latter would be for  
> experts so it could be brief.

That's why I've been saying we shouldn't try in this chapter at all:  
because we can't give good authoring rules independent of  
serialization. However, there's really no reason for this chapter to  
discuss syntax at all. That's a topic for another earlier chapter. An  
earlier chapter can discuss how to build an element in either of the  
two serializations; how to nest elements, etc. This chapter is on the  
"Semantics and structure of HTML elements". It just doesn't need to  
get into syntax.

>
>> There may be some other way to artfully avoid any discussion of  
>> serialization and syntax and may that's the way to go here.  
>> However, it would be incorrect to say that some elements do not  
>> have close tags because that's dependent on the text/html  
>> serialization. From the disagreement here and on further  
>> reflection, perhaps this introduction should just avoid  
>> syntactical issues and focus on the document as a tree of elements  
>> (elements with content and attributes and nothing more). Then we  
>> don't need to talk about the specifics of how those elements are  
>> serialized  or syntactically constituted.
>
> That doesn't seem like it would be helpful to content authors. We  
> want to help them write a document, right? If we want to help them  
> write both text/html and text/xml documents, we'll need two  
> different sections.

Yes, we want to help authors write a document, but not everything has  
to be accomplished in chapter 3.

>
>> I started off my post by saying I thought there was a danger of  
>> going into too much detail here. I stand by that. I really don't  
>> think a discussion of syntax is necessary in this introductory  
>> section. Elements, content models, attributes, semantics, default  
>> or sample presentation, etc. Forget about tags and short-hand  
>> notation. That's for another chapter.
>
> Starting novices off by talking about the document tree instead of  
> the actual syntax of a document sounds unlikely to make for good  
> pedagogy. The DOM is something that doesn't make much sense until  
> you know what an element is.

First, I'm not suggesting we start with novices off telling them  
about the document tree. I'm suggesting we start off chapter 3 that  
way. Also, knowing what an element is does not require that one know  
how to make an element syntactically. It only requires that one know  
that an element has attributes  that take values of specific types  
and content that accepts a specified content mode. The content model  
may have minimum requirements and tmay have prohibited content. As  
for the DOM in the narrow sense of the term (i.e., in terms of API)  
that is a part of this chapter that many will skim (or even skip)  
over. However, everyone must understand the broader sense that a  
document is comprised of a tree of nested elements.

Just to reiterate, I'm not suggesting we shouldn't discuss syntax in  
our recommendation. I'm merely suggesting that chapter 3 on the  
semantics and structure of HTML elements may not be the place for it.  
Especially given the controversy in this WG over how to advise  
authors,, its a can of worms that will eclipse the entire point of  
this chapter.

Take care,
Rob

Received on Tuesday, 17 July 2007 18:17:56 UTC