Comments on 2nd WD of XSL specification (Chapter 1)

Editors:

Here are some comments/recommendations for part of the first chapter of 
the second WD (most are minor editorial in nature): 

Chapter One -- Introduction and Overview

1.)  Section 1.1 -- Third paragraph:  Make the first instance of 
"formatting properties" in this paragraph bold, and unbold the 
subsequent bolded references of "formatting properties" and "formatting 
objects" in this same paragraph.  (the latter has already been shown 
bolded earlier in the paragraph).


2.)  Section 1.1 -- The diagram labelled "XSL Two Processes:  
Transformation & Formatting" -- rename "(element and attribute nodes)" 
to "(element and attribute tree)" to make consistent with the text. 
(Also perhaps best to change the ampersand in the label to an "and"?  
I'm not sure.)


3.)  Section 1.1.1 -- The diagram labelled "Transform to Another 
Vocabulary" -- same change as (2) above for the same reason.


4.)  Section 1.1.1 -- Third paragraph:  Change:

"This would allow an XML document which contains formatting objects and 
formatting properties to be output."

to

"This would allow -->for<-- an XML document -->that<-- contains 
formatting objects and -->properties<-- to be -->viewed.<--"

(output->viewed switch to avoid verb repetition with previous sentence.)


5.)  Section 1.1.1 -- Third paragraph:  Change:

"To preserve accessibility, designers of Web systems should not develop 
architectures that require (or use) the transmission of documents 
containing formatting objects and properties unless either the 
transmitter knows that the client can accept formatting objects and 
properties or the transmitted document contains a reference to the 
source document(s) used in the construction of the document with the 
formatting objects and properties."

to

"To preserve accessibility, designers of Web systems should not develop 
architectures that require (or use) the transmission of documents 
containing formatting objects and properties unless --><-- the 
transmitter knows that the client can accept formatting objects and 
properties."

("either" removed, also truncating the sentence at "...objects and 
properties." because what follows (i.e., providing links to the source 
document) appears too speculative a solution.  (i.e., even if one 
provided the pre-XSL namespace source documents, how would the client 
know which data from the source document to use and in what order, etc, 
given that the XSLT process provides filtering and sorting?  
Furthermore, the client would also need to know how to work with the 
source documents, so this part of the sentence is not sufficiently 
rigorous to be provided as an alternate solution.)


6.)  Section 1.1.2 -- First paragraph.  Change:

"Formatting interprets the result tree in its ormatting object tree form 
to produce the presentation
intended by the designer of the stylesheet from which the XML element 
and attribute tree in the "fo" namespace was constructed."

to

"Formatting interprets the result tree --><-- to produce the 
presentation intended by the designer of the stylesheet from which 
-->this<-- tree --><-- was constructed."

(Too many redundancies here--simplification makes it easier to 
understand.  Also, instead of "result tree" in the replacement sentence, 
can alternatively use "element and attribute tree", I'm unsure which is 
better.)


7.)  Section 1.1.2 -- The diagram labelled "Build the XSL Formatting 
Object Tree" -- change the '"fo" namespace' text to "XSL namespace" 
(This seems to be a good point in the recommendation to always start 
using "XSL namespace" instead of "fo namespace".)

Recommend doing a search on "namespace" from this point on in the 
recommendation, and to change all subsequent references of "fo 
namespace" to "XSL namespace".  (Whether or not to do this before this 
instance I am unsure.)


8.)  Section 1.2, third paragraph.  Remove this sentence from the paragraph:

"While many of XSL's formatting objects and properties correspond to the 
common set of properties, this would not be sufficient by itself to 
accomplish all the goals of XSL."

(The sentence is somewhat awkwardly written--especially the "correspond 
to the common set of properties" in order to say that FO's and 
properties are partly derived from CSS2 and DSSSL--and I can't come up 
with a better alternative.  At any rate, It's not adding anything that 
meaningful because the derivation of XSL from these two standards is 
already stated in the sentence preceding this one, and much better 
elaborated on in just a few paragraphs ahead of this, so I recommend 
just removing the sentence entirely.)


9.)  Section 1.2.1, second paragraph.  Change from:

"To achieve this control, XSL has extended the set of formatting objects 
and formatting properties."

to

"To achieve this control, XSL has extended the set of formatting objects 
and formatting properties beyond those available in either CSS2 or DSSSL."

(The extension of XSL from these standards is the main emphasis of this 
area.  The second "formatting" may also be considered redundant here.)


10.)  Section 1.2.1, second paragraph.  Change the -->can<-- to "are to".

In addition, the selection of XML source components that -->can<-- be 
styled (elements, attributes, text nodes, comments, and processing 
instructions) is based on XSLT and XPath [XPath], thus providing the 
user with an extremely powerful selection mechanism.


Thanks,

Glen Mazza
Apache FOP Team

Received on Wednesday, 22 December 2004 02:28:28 UTC