Comments on 2nd WD (part 9)

Editors:

More comments on the XSL 1.1 2WD:

81. Section 6.1, 2nd paragraph.  The WD defines three
types of formatting objects:  (1) those that generate
areas, (2) those that just return areas, and (3) those
used in the generation of areas.  This third type is
defined as a "layout object" or "auxiliary object". 
You may wish to break up this third type--i.e.,
distinguish layout objects (type 3) from auxiliary
objects (new type 4).  This fourth category would
include objects such as fo:declarations and
fo:color-profile (and possibly the bookmark FO's) that
really aren't used in the generation of areas as, say,
the fo:layout-master-set (type 3) is.


82.  Section 6.4.1.1, Page-Sequence-Masters:  Consider
removing the first paragraph (repeated below) of this
section.  It is cumbersome to read and I am not
certain it is accurate (especially the last sentence).
 Further, the paragraph after this one says much the
same as this paragraph but much more clearly.

"Each fo:page-sequence-master characterizes a set of
possible sequences of page-masters. For any given
fo:page-sequence, only one of the possible set of
sequences will be used. The sequence that is used is
any sequence that satisfies the constraints determined
by the individual page-masters, the flows which
generate pages from the page-masters, and the
fo:page-sequence-master itself."


83. Section 6.4.1.2, Page-Masters.  Add -->a<-- where
indicated:

A region specification is used as a master, the
region-master, in generating -->a<--
viewport/reference pair consisting of a
region-viewport-area and a region-reference-area.


84. Section 6.4.1.4, Flows and Flow Mapping, 2nd
paragraph.  Recommend adding text as indicated:

No two flows -->within the same page-sequence<-- may
have the same name.


85. Section 6.4.1.4, 4th paragraph.  Recommend
updating the following paragraph:

"The flow-map is specified by the fo:flow-map
formatting object; if this object is not present then
the flow-map is implicit, as in version 1.0 of this
Recommendation.  The 'flow-name' property of a flow
specifies to which region that flow is assigned. Each
region has a 'region-name' property. The flow-map
assigns a flow to the region that has the same name."

Reasons: (1) it implies that there is only one
flow-map for an FO document, and (2) while the first
sentence is strictly correct, the flow-map is implicit
for a *page-sequence*, not the document as a whole. 
(i.e., there can be several flow-maps defined, but if
a fo:page-sequence does not have flow-map-reference
specified, then the implicit flow-map would still be
in effect for that page-sequence.)  Also, (3) the last
two sentences are relevant only for the implicit
flow-map (this text is from 1.0), but is written here
as if it is relevant for all flow-maps.

Possible replacement text:

"Flow-maps are specified by fo:flow-map formatting
objects.  A fo:page-sequence uses the flow-map
indicated by its flow-map-reference property in
assigning its flows to regions.  If the
flow-map-reference property is not specified for the
page-sequence then the implicit flow-map is used for
that page-sequence.  See 6.4.5, fo:page-sequence, for
the definition of the implicit flow-map."


86.  Section 6.4.1.4, 5th paragraph.  Recommend
changing "default" to "same" as follows:

It is an error for a page master to have two
region-body descendants with the [default-->same]
region-name.

(I still am not sure why the WD was modified to allow
more than one region-body for a
simple-page-master--see #62 [1].  I am assuming it is
somehow related to the new fo:flow-map,  but if this
is the reason it would appear then *all* region
classes should then be allowed to have more than one
instance.)

[1]
http://lists.w3.org/Archives/Public/xsl-editors/2005JanMar/0011.html


87.  Section 6.4.1.6 Pagination Tree Structure. 
Recommend switching "result" to "pagination" below:

"The [result-->pagination] tree structure is shown
below.

And possibly, the Editors may wish to add an
fo:flow-map to this diagram, possibly removing
fo:declarations to save space (fo:bookmark-tree is not
present here, so fo:declarations perhaps need not be
either.)


88.  Section 6.4.2, fo:root, first paragraph.  The
second sentence should perhaps be updated for XSL 1.1.
 Possibly change from:

It holds an fo:layout-master-set formatting object
(which holds all masters used in the document), an
optional fo:declarations, and one or more
fo:page-sequence objects.

to:

It holds an fo:layout-master-set formatting object
(which holds all masters and flow-maps used in the
document), optional fo:declarations and
fo:bookmark-tree objects, and one or more
fo:page-sequence objects.


89. Section 6.4.5, fo:page-sequence, first paragraph. 
The parenthesized expression in the statement below
needs to be updated to account for the fact that the
XSL 1.1 now allows for more than one fo:flow per
fo:page-sequence:

"The content of these pages comes from flow children
(consisting of the single fo:flow and any
fo:static-content flow objects) of the
fo:page-sequence."


90. Section 6.4.5, fo:page-sequence, "Areas" section
(second paragraph).  I think it would be clearer to
have the fo:page-sequence *return* a title-area rather
than generate it.  (This would be allowed by the WD,
because the second paragraph of section 6.1 states
that formatting objects that generate objects may
"both generate and return areas".)  In turn, have the
fo:title generate the title-area, rather than just
have it return its children to the fo:page-sequence
for the latter to generate this area.

If this is done, the constraints section beginning
with "If a title-area is generated..." in the
fo:page-sequence description can then be moved to
fo:title (section 6.4.21), putting descriptions of
fo:title and title-areas conveniently in one place for
the reader.


Thanks,
Glen Mazza
Apache FOP Team

Received on Wednesday, 9 March 2005 01:55:23 UTC