Comments on 2nd WD (part 3)

Editors:

More suggestions for the 2nd WD:

21.)  Section 1.2.6, 1st paragraph.  Recommend replacing "the dual" 
below with "both the".

Therefore, XSL has a formatting object that expresses -->the dual<-- 
semantics of formatting the content of the link reference and the 
semantics of following the link.


22.)  Section 3, 2nd paragraph. Remove the hyphen from 
"placement-constraints" (it is not a trait, and does not exist elsewhere 
in the document in this hyphenated form) and provide a small definition 
for "stacked areas" as follows:

"4 Area Model will describe the area tree and define the default 
placement constraints on stacked (contiguously placed) areas."

Reading the Recommendation the first time through, the meaning of 
stackable/stacked/stacking, etc., was not immediately clear to me.  
Providing an early definition here that "stacked areas" means 
"contiguously placed areas" will help quickly clarify the topic for the 
reader before he/she reads further.


23.)  Section 3, 4th paragraph.  Change the following sentence:

"This refers to the types of areas -->which<-- they generate, which in 
turn -->refer to<-- their default placement method."

to

"This refers to the types of areas -->that<-- they generate, which in 
turn -->specifies<-- their default placement method."

(Can also use "indicates" instead of "specifies").


24.)  Section 3, 8th paragraph.  Switch from "-->which<--" to 
"-->that<--" in the below:

"To summarize, formatting proceeds by constructing an area tree 
(containing areas and their traits) -->which<-- satisfies constraints 
based on information contained in the XML result tree (containing 
element nodes and their attributes)."

(although debatable but "that" seems more natural:  
http://andromeda.rutgers.edu/~jlynch/Writing/t.html#that)


25.)  Section 3.1, 2nd paragraph.  Change:

"Each object, while being processed, may initiate processing -->in<-- 
other objects. While the objects are hierarchically structured, 
-->the<-- processing is not;"

to

"Each object, while being processed, may initiate processing -->of<-- 
other objects. While the objects are hierarchically structured, 
-->their<-- processing is not;"


26.)  Section 3.1, 2nd and 3rd paragraph.  If possible, recommend 
switching from a co-routine example to a subroutine one.

The sample algorithm suggests using co-routines [1] rather than simpler 
subroutines [2].  Coroutines appear quite rare, not naturally available 
in most programming languages.  Also, they don't appear to be as useful 
in an XSL processing scenario.

The second paragraph states "[...] processing of a given object is 
rather like a co-routine which may pass control to other processes, but 
pick up again later where it left off."  However, this can also be done 
by a subroutine, which can call other subroutines and pick up again 
later after the called subroutine returns.  

The third paragraph states "[...] processing a formatting object creates 
areas and returns them to its parent to be placed in the area tree. Like 
a co-routine, it resumes control later and initiates formatting of its 
own children (if any), or some subset of them."  But this seems very 
unnatural.  It would appear that an FO would not return an area to its 
parent until its child FO's have further elaborated that area first:  
Why bother sending an empty block to the parent FO, and *then* the inner 
contents of that block (without the enclosing block), for the parent to 
somehow merge together?  Switching to a subroutine example, where the 
block would be fully developed internally and *then* returned to the 
parent as a unit, would appear to be a better approach..

[1] http://en.wikipedia.org/wiki/Coroutine
[2] http://en.wikipedia.org/wiki/Subroutine


27.)  Section 3.1, 7th paragraph.  Perhaps best to switch from 
-->placement<-- to -->stacking<-- in the below sentence:  

In particular, size and position of the areas will be subject to the 
-->placement<-- and spacing constraints described in the area model, 
unless the formatting object definition indicates otherwise.

(Reason:  "Stacking" is the standard term being used for "placement" in 
the recommendation.)


28.)  Section 4.0, 1st paragraph.  Change:

"This section defines the general model of --><-- areas and how they 
interact. The purpose is to present an abstract framework -->which is 
used<-- in describing the semantics of formatting objects."

to

"This section defines the general model of -->these<-- areas and how 
they interact. The purpose is to present an abstract framework -->that 
will be used<-- in describing the semantics of formatting objects."

("these" ties this sentence to the sentences preceding it, making the 
paragraph more coherent.)

29.) Section 4.1, 3rd paragraph (the Note).  Change:

"The only exceptions --><-- are when several leaf nodes of the 
formatting object tree are combined to generate a single area, for 
example when several characters in sequence generate a single ligature 
glyph. -->In all such cases<--, relevant properties such as font-family 
and font-size -->are<-- the same for all the generating formatting objects"

to

"The only exceptions -->to this rule<-- are when several leaf nodes of 
the formatting object tree are combined to generate a single area, for 
example when several characters in sequence generate a single ligature 
glyph. -->For this type of combining to occur, however<--, relevant 
properties such as font-family and font-size -->would need to be<-- the 
same for all the generating formatting objects"


30.) Section 4.1, 5th paragraph.  Recommend removing this sentence:

"Traits whose values are copied or derived from a property of the same 
or a corresponding name are listed in C Property Summary and 5 Property 
Refinement / Resolution; other traits are listed below."

and placing a new sentence just before the last paragraph in Section 4.1 
(The one that starts with "The indirectly-derived traits are..."):

"Directly-derived traits are listed in C Property Summary and 5 Property 
Refinement/Resolution."


Thanks,
Glen Mazza
Apache FOP Team

Received on Friday, 31 December 2004 04:22:21 UTC