Re: 3.1 Introduction (Draft), review of

Hi Debi,

I think overall, that would make a good introduction to the chapter.   
It's well-written and provides the most of the summary items needed  
to read the chapter. Others have suggested some tightening of the  
language. I'll try to summarize what I think is important in those  
suggestions here. Some of the comments (including my own) are largely  
due to the draft needing to be further along before we can properly  
summarize it in an introduction section (as Laura Carlson's post  
pointed out.

First, I think there's a danger of going into too much detail  
regarding optional tags. The only things I think might need to be in  
an introductory section (maybe) are:

1) that empty elements must have their closing tag omitted unless an  
author uses the xml-style self-closing tag (e.g., <link />).
2) that empty elements must be closed when using the xml  
serialization: i..e., either (<link></link> or <link />)

So to avoid this confusion and simplify things, it may make sense to  
always recommend (or as far as this introduction goes, just gloss- 
over the difference so that authors use) the self-closing tag for  
empty elements.

It may be useful to draw attention to the way each element in the  
chapter indicates its content model including whether it is required  
to be empty.

As far as terminology goes, the important things to differentiate are:

1) elements are bounded by opening and closing tags
2) tags and elements: tags (not elements) are bounded by angle  
brackets, i.e., < >..
3) empty v. self-closing: elements you refer to as self-contained are  
generally called empty elements (the tag may be thought of as self- 
contained in  the sense that when someone uses xml syntax the tag  
opens and closes the element, but I do no t think that usage is  
widely deployed).
4) interpret v. render: I would also agree with Olivier Gendrin who  
suggested using the term interpret rather than render (since certain  
interpretation goes on in browsers and even more so in UAs more  
broadly defined that isn't related to rendering.

Finally, on the issue of the optionality of tags, I think it is an  
issue that probably is too detailed for an chapter  introduction  
section (especially since it differs between the two serializations).  
Since the chapter is more concerned with the semantics of HTML5, its  
fair to say that all elements have tags (even if their inferred by  
the parser and implied by the document). Again, the only thing  that  
might be worth mentioning in the introduction is that empty elements  
have no separate closing tag (i.e., they may have the xml short-hand  
"/" self-closing tag, but not an explicit closing tag </elementname>) .

Olivier Gendrin, I'm not clear why you thought the paragraphs should  
be combined.

I added the scoped style element, though I would say that's still a   
controversial part of the draft (i.e., we still need to come up with  
a compelling use-case for it).

Other than that, I think it would make a good introductory section. I  
marked up your original draft with some insertions (double underscore  
"__") and deletions (double hyphen-minus "--"). I was trying to  
change the minimum in the document based on he comments above. I'm  
sure you would do a better job than I did with these insertions/ 
deletions with a minor (though more coherent) redraft.

------------------------------------------

COPY-EDITED REVIEW:
On Jul 15, 2007, at 1:22 PM, Debi Orton wrote:

3.1  Introduction (novice level)

Hypertext Markup Language (HTML) is one of several markup languages  
used to organize information for delivery on the WorldWide Web.   
Elements in HTML have specific purposes, in many cases to delineate  
the structure or hierarchy of the document's information.  Adherence  
to the use of elements for their specific purpose __—rather than, for  
example, their default presentation—__ is referred to as "semantic  
markup."

HTML elements are instructions inserted within a pair of __tags which  
themselves are bounded by a pair of__ angle brackets(<>).  The  
contents within the angle brackets __of the opening tag__ tell the  
browser how to __interpret__--render-- the content within the  
element__ (the contents between the pair of tags)__.  Further  
instructions for the browser can be conveyed by one or more  
attributes/value combinations indicating in more detail how the  
element is to be interpreted.  Collectively, the angle bracket, the  
element's name, and any attributes modifying it are often referred to  
as a "tag."

__Tags__--Elements-- are paired, meaning that in order to apply an  
element to a section of information within the document, the section  
must begin with an opening element tag (e.g., <p>) and must end with  
a closing element tag (e.g., </p>).  Some elements also have  
mandatory attributes, such as the <img> element's src attribute that  
indicates the location from which an image is to be loaded, or the  
type attribute of the <script> element.

There are exceptions to the opening/closing element model, primarily  
for elements that are __empty__--self-contained--, such as the  
element describing the document's metadata (<meta>), the <link>  
element, and the line break element (<br>).__ For the xml  
serialization these elements must have closing tags and for the MIME  
type text/html these elements must not have a closing tag. __For  
these single elements, a slash is inserted just before the element's  
closing angle bracket __to work in either serialization__(e.g., <br />).

HTML documents are comprised of two major sections.  The head section  
(<head>) includes the metadata information, stylesheet and script  
information, and the document's title.  The body section includes the  
document's content, and any associated markup.

The way that information is presented is typically governed by style  
information, contained either__: 1)__ in the head of the document by  
use of the <style> element__; 2) in the body of the document by use  
of a scoped style element; __ or__ 3)__ in an external style sheet,  
which is referenced by a <link> element.  Segregating the style  
information to an external style document allows the author to  
reference one master set of styles from multiple documents, which  
makes it easier to maintain the look and feel of a collection of  
documents.  To the extent possible, presentational information should  
be excluded from the body of the HTML document, which preserves the  
semantic usage of elements and their attributes.

------------------------------------------

ORIGINAL REVIEW:
On Jul 15, 2007, at 1:22 PM, Debi Orton wrote:


This is my draft of the content for 3.1, described as "An  
introduction to marking up a document."  I offer it as a starting point.


3.1  Introduction (novice level)

Hypertext Markup Language (HTML) is one of several markup languages  
used to organize information for delivery on the WorldWide Web.   
Elements in HTML have specific purposes, in many cases to delineate  
the structure or hierarchy of the document's information.  Adherence  
to the use of elements for their specific purpose is referred to as  
"semantic markup."

HTML elements are instructions inserted within a pair of angle  
brackets(<>).  The contents within the angle brackets tell the  
browser how to __interpret__--render-- the content within the  
element.  Further instructions for the browser can be conveyed by one  
or more attributes/value combinations indicating in more detail how  
the element is to be interpreted.  Collectively, the angle bracket,  
the element's name, and any attributes modifying it are often  
referred to as a "tag."

Elements are paired, meaning that in order to apply an element to a  
section of information within the document, the section must begin  
with an opening element tag (e.g., <p>) and must end with a closing  
element tag (e.g., </p>).  Some elements also have mandatory  
attributes, such as the <img> element's src attribute that indicates  
the location from which an image is to be loaded, or the type  
attribute of the <script> element.

There are exceptions to the opening/closing element model, primarily  
for elements that are self-contained, such as the element describing  
the document's metadata (<meta>), the <link> element, and the line  
break element (<br>).  For these single elements, a slash is inserted  
just before the element's closing angle bracket (e.g., <br />).

HTML documents are comprised of two major sections.  The head section  
(<head>) includes the metadata information, stylesheet and script  
information, and the document's title.  The body section includes the  
document's content, and any associated markup.

The way that information is presented is typically governed by style  
information, contained either in the head of the document by use of  
the <style> element or in an external style sheet, which is  
referenced by a <link> element.  Segregating the style information to  
an external style document allows the author to reference one master  
set of styles from multiple documents, which makes it easier to  
maintain the look and feel of a collection of documents.  To the  
extent possible, presentational information should be excluded from  
the body of the HTML document, which preserves the semantic usage of  
elements and their attributes.

------------------------------------------
Take care,
Rob

Received on Tuesday, 17 July 2007 01:15:43 UTC