XML Pocket Reference
by Robert Eckstein

Unconfirmed error reports are from readers.  They have not yet been 
approved or disproved by the author or editor and represent solely the
opinion of the reader.

This page was updated March 28, 2001.

Here's a key to the markup:

        [page-number]: serious technical mistake
        {page-number}: minor technical mistake
        <page-number>: important language/formatting problem
        (page-number): language change or minor formatting problem
        ?page-number?: reader question or request for clarification


UNCONFIRMED errors and suggestions from readers:


[9]  Example 2:
None of the XML editors or parse engines will swallow this version of the DTD.
They seem to require the "xmlns" attribute for each element to be defined in 
the DTD, in other words, they require the DTD to contain the following:

<!ELEMENT OReilly:Books (OReilly:Product,OReilly:Price) >
<!ELEMENT OReilly:Product (#PCDATA) >
<!ELEMENT OReilly:Price (#PCDATA) >
<!ATTLIST OReilly:Books xmlns:OReilly CDATA #FIXED "http://www.oreilly.com/">
<!ATTLIST OReilly:Product xmlns:OReilly CDATA #FIXED "http://www.oreilly.com/">
<!ATTLIST OReilly:Price xmlns:OReilly CDATA #FIXED "http://www.oreilly.com/">

I've looked at both REC-xml-19980210 and REC-xml-names, and I cannot find a 
definitive answer as to which is correct. My interpretation would actually be 
that that the first ATTLIST should be adequate to define the xmlns:OReilly 
attribute for the child elements. More explicitly, I would expect the 
following to be correct:

<!ELEMENT OReilly:Books (OReilly:Product,OReilly:Price) >
<!ELEMENT OReilly:Product (#PCDATA) >
<!ELEMENT OReilly:Price (#PCDATA) >
<!ATTLIST OReilly:Books xmlns:OReilly CDATA #FIXED "http://www.oreilly.com/">

Whatever, it would be better if the example given worked with commonly 
available applications (the Win32 ones I've tried are:

Microsoft's IE5
IBM's Xeena
Evrsoft's 1st Page 2000
Wattle Software's XMLWriter ).


?10? "parentheses specify required elements": is uninformative and misleading,
as they could be EMPTY or optional (with ? or *). The point is that anything 
following the ELEMENT name are names and rules for _contained_ ELEMENTS (if 
any).


[14] first paragraph:
In addition to the other "unconfirmed error" reporting the changes neccessary 
to display the blank page with the sample.xml, simple.dtd and simple.xsl 
examples, a declaration of the simple.xsl stylesheet is required in the 
sample.xml file.


[14]  2nd paragraph:
The book erroneously claims that the sample comprised of simple.xml, 
simple.dtd, and simple.xsl will work.  I created these files verbatim from the
text and opened the file simple.xml in IE5.  I received an error claiming that
the xsl:text element could not be used.  I deleted the two xsl:text elements 
from simple.xsl and tried again - this time it parsed the document and printed
a blank page in the browser. 


{14}  1st bullet under "Well-formed XML":
Paragraph reads: "The document must either use a DTD or contain an XML 
declaration with the standalone attribute set to 'no'."

The attribute should be set to "yes" for a document that stands alone without 
a DTD.


{16} DOCYTPE:
On page 37, DOCTYPE can suddenly contain a additional [ ... ] block, 
describing  the internal subset. A note or reference to this page might be 
helpful.


(19)  3rd paragraph:
In the paragraph's last sentence -- i.e., "Otherwise, you should check the 
element declaration in the DTD to determine the exact semantics." -- the term 
"semantics" should be replaced by "syntax".


(20-21) xml:space attribute:
"The XML processor is free to do whatever it wishes" could cause 
misunderstandings.


(31) 2nd paragraph:
	
	"The XML processor is free to use or ignore ..." 

The word "ignore" could cause misunderstandings; in every case the processor 
has to pass on the information to the application. An addition with a note 
like this is suggested.

[31]  top, 1st code example;
I think there is a contradiction between the example referenced and the XML 
spec.  I would recommend that you run it by an expert first though, because 
I could well be wrong.

The example has a entity reference to a unparsed entity, as follows:

<image src="&image1;"/>

however, the XML spec says in section 4.1:

 > Well-formedness constraint: Parsed Entity
 > An entity reference must not contain the name of an unparsed
 > entity. Unparsed entities may be referred to only in attribute
 > values declared to be of type ENTITY or ENTITIES.

because the example shows an entity reference to an unparsed entity, I 
think it may violate the quoted constraint, and is therefore a potentially 
incorrect and misleading example.

Also worth noting is that the example at the top of page 35 is correct, 
because it uses an attribute value of type ENTITY.


{31/35} should contrast p31: <image src="&image;"/> with p35: <image 
src="image">


{40 ff.} The order of elements ought to be replaced with the more up to date 
ones at http://www.w3.org/TR/xslt#stylesheet-element.

None of the old style syntax that you have will work with xalan 1.0.1, and 
thus, in particular, it won't work with Cocoon.


{57 ff.} <xsl:arg name="fooarg" value="bar"/> becomes <xsl:with-param 
name="fooarg"> bar </xsl:with-param> (note the change of syntax, and note also
that the syntax for <xsl:arg /> seems to have been wrong anyway; 
default="value" ought surely to have been value="value").

<xsl:invoke > (which is not in the pocket reference, but belonged with the 
original syntax, and is mentioned  on p. 58, top para) is replaced by 
<xsl:call-template>

The example at the top of p. 58 ought to be replaced by the following (from  
http://www.w3.org/TR/xslt#element-with-param):

<xsl:template name="numbered-block">
  <xsl:param name="format">1. </xsl:param>
    <fo:block>
     <xsl:number format="{$format}"/>
      <xsl:apply-templates/>
    </fo:block>
</xsl:template>

<xsl:template match="ol//ol/li">
 <xsl:call-template name="numbered-block">
  <xsl:with-param name="format">a. </xsl:with-param>
 </xsl:call-template>
</xsl:template>


{60} bottom entry:
<xsl:contents/> is now redundant.


(64)  code snippet for the <xsl:for-each> tag:
The code snippet uses the <xsl:process> tag, which is undocumented in the book.


[67] bottom entry <xsl:macro>:
<xsl:macro> is now dead, and has been replaced by the concept of a named 
template. 

<xsl:macro name="foo"> becomes <xsl:template name="foo">.


{68} middle paragraph:
<xsl:macro-arg name="fooarg" default="bar"/> becomes <xsl:param name="fooarg">
bar </xsl:param> (note the change of syntax).


[73]  4th paragraph (code example):
The code example for ID references contains an internal subset that defines 
attributes for a <person> element. These attributes should be defined for the 
<employee> element, similar to the 3rd paragraph of page 34.