comments on the XSL draft of 27 March 2000

1.  The diagram at the end of 1.1 says 
"syntactically, [Result XML] is XML elements and attributes."
This isn't accurate, as Result XML needn't syntactically be 
anything, it is a tree (or infoset) of objects.  I suggest removing 
that whole sentence from the box in the graphic since it is 
erroneous and unnecessary given that the immediately following 
paragraph describes the result tree in proper terms.

2.  The last diagram in 1.1.2 shows the generation of the
area tree, but the arrow between the two trees is labelled
"XSL Formatting Area Tree".  Instead, it should just be
labelled "XSL Formatting Area Tree Generation" or something,
because the process isn't the area tree, it produces the
Area tree.

3.  In 1.2.1 Paging and Scrolling, in the para talking about
the splitting up of the white-space property, it talks about
a "line-feed" property that should be "linefeed-treatment".

4.  In 3 Introduction to Formatting, second para, it says:
"...traits, which are to areas what properties are to 
formatting objects and attributes are to XML nodes."  I
think the last word should be "elements", not "nodes" for
the analogy to be in its clearest form.

For example, note in section 4.1 we say "Each area has a set
of traits, a mapping of names to values, in the way elements 
have attributes and formatting objects have properties."

5.  In 4.1, the para after the first graphic, there is a
sentence that reads in part "Traits whose values are 
copied from property of the same or a corresponding
name are listed in [C Property Index]...."  There appears
to be a missing word in "copied from property".

6.  In 4.3 Spaces and Conditionality, the first sentence
lists the components of a space specifier as "minimum, 
optimum, and maximum, conditionality, and precedence."
The "and" between optimum and maximum shouldn't be there,
and may lead to confusion.

7.  In 4.3.1 Space-resolution Rules, the second para of 
point 3, starts "Otherwise, when there are at two or more 
space-specifiers all of the same highest precedence...."
I think "there are at two or more" should instead read
"there are two or more" (delete "at").

Also, the example in that section starts with "Example. 
Suppose the sequence of space values occurring at the 
beginning of a reference-areas is:"  That should be
"of a reference area is" (reference-area shouldn't be
pluralized).

The penultimate paragraph of this section starts with
"The padding of a block-area does not interact with 
the any space-specifier...."  Problem with "the any".

8.  In 4.3.1 Space-resolution Rules, I don't see (except 
where it is implied in the example) where it is said how 
the conditionality of the resolved space is determined or
even if resolve space should have conditionality (since
conditionality is really only relevant in the resolution
process).  Something needs to be said about this.

9.  In 5.1.2, the penultimate sentence reads:
  However, there are some properties whose specified
  value may be inherited (e.g., the value for the
  "line-height" property).
But this is not true for all values of the line-height 
property, only in the case where the value is a unitless 
number (giving a factor by which to multiple the font size).
So I suggest this be reworded as follows:
  However, there are some properties whose specified
  value may be inherited (e.g., some values for the
  "line-height" property).

10. Twice in 5.3 and once in 5.3.1, "correspondance" -> 
    "correspondence" (spello).

11. In 5.8.11 Lexical Structure, the first bullet point reads:
  If the character following an NCName (possibly after
  intervening ExprWhitespace ) is "(", then the token
  must be recognized as FunctionName.
I would rather we deleted the parenthetical phrase.  In
most programming languages and other notations, if one puts
whitespace between the name and the open paren, it is no
longer recognized as a function call, and I think this
behavior is more common and makes more sense and is more
in keeping with the analogous case of putting space around
minus (-) signs to avoid them being considered part of a 
name and requiring no space between numbers and unitnames.

12. Also in 5.8.11, last bullet point includes the word
"numeric" but fails to tag it correctly.  Since it is
important here that "Numeric" (uppercase N) refers to
the token in production 5 of our expression language,
this needs to be retagged appropriately.

13. In 5.9.4 Property Value Functions, the 
inherited-property-value function returns the inherited 
value of the given property.  I'd like to make it clearer
just what is the inherited value.  I suggest the following
wording and example:

  The returned "inherited value" is the computed value 
  of this property on this objects parent.  In particular,
  given the following example:

  <fo:list-block>
    <fo:list-item color="red">
      <fo:list-item-body background-color="green">
        <fo:block background-color=inherited-property-value(color)>
        </fo:block>
      </fo:list-item-body>
    </fo:list-item>
  </fo:list-block>

  The background-color property on the fo:block is assigned
  the value "red" because the (computed, after inheritance)
  value of the color (not background-color) property on the
  fo:block that is the parent of fo:inline is "red".

14. In 5.9.4 Property Value Functions, under the
proportional-column-width writeup, it says that "function
returns proportional factor (the argument) units of proportional 
measure."  Im having a bit of trouble parsing that sentence.
I assume we're just saying that the function returns N units
of proportional measure where N is the argument given to this
function, and I would prefer some such wording.

15. In 5.9.4 with respect to proportional-column-width,
we say that it is an "error to use this function on 
formatting objects other than an fo:table-column" but I don't
see why we don't allow the use of this function anywhere
within a table.  For example, why couldn't someone want to
set, say, indents within a table cell to some fraction of
the proportional-column-width?  Or perhaps make use of the
proportional-column-width in an xsl-if test to decide what
font-size to use somewhere or make some other decision?  
I'm not suggesting we allow the * syntax elsewhere, but since
an implementor has to implement the proportional-column-width
function and handle it when it is given within an expression
in an attribute value on the fo:table-column FO, what's so hard
about allowing that function in other expressions within the
table.  It sort of seemed like it might be more work to forbid
such use than just allow it, and some users might find it useful.

16. In 5.10 Property Datatypes, the last sentence of the
second para reads (typo):
  For example a the "space-before" property may be specified as:
              ^^^^^

17. In 5.10 Property Datatypes, under the description of the 
short form, we say:
  Such a specification gives that value to each of the numeric
  components and the initial value to all the non-numeric components.
But space-before.precedence is a numeric component, yet we want
to use the initial value, not the given value, in this case.  
Therefore, instead of:
  A short form of compound value specification may be
  used, in cases where the datatype has some numeric
  components. Such a specification consists of giving
  a numeric value to an attribute with a name matching a
  property name. Such a specification gives that value to
  each of the numeric components and the initial value to all
  the non-numeric components. 
I suggest:
  A short form of compound value specification may be
  used in some cases. Such a specification consists of giving
  a single value to an attribute with a name matching a
  property name. Such a specification gives that value to
  some of the components and the initial value to other
  components.  Each property description describes any allowable
  short form and how it affects that compound property.

18. In 5.10, our defn of the <name> datatype reads:
  A string of characters representing a name. It must not
  contain any whitespace, or space characters. 
First, saying whitespace or space characters seems odd/redundant.
Second, is this really a proper defn?  Aren't there lots of
other characters that cannot be in a name?

19.  In section 5.10 we define the datatype <uri> as:
  A sequence of characters conforming to a URI value
  as specified in the URI specification. 
but this is ambiguous and does not use standard terminology.  
I suggest we change it to read:

  A sequence of characters conforming to a relativeURI value
  as specified in [RFC 2396]. 

The term "relativeURI" is defined in section 5 of RFC2396.  This
would allow relative URIs without allowing fragment identifiers.

Note that the <uri> datatype is used in XSL in section 7.36.7 
as the type of the "src" property, and note that the <IMG> 
element's src attribute in HTML clearly allows relative URIs;
see Section 6.4 URIs of the HTML 4.01 spec
http://www.w3.org/TR/html401/types.html#type-uri
which says:
  Relative URIs are resolved to full URIs using a base URI.
  [RFC1808], section 3, defines the normative algorithm for
  this process. 
(but note that RFC 2396 supercedes RFC 1808 now).

20. In the third from last para of "6.1.1 Definitions 
Common to Many Formatting Objects", there is a typo:
  Out-of-line areas are areas used outside the normal
  flow of text either because the are absolutely positioned
                              ^^^
                             they

21. At the end of 6.2, we say (about float and footnote):
  The following "out-of-line" formatting objects may be
  used anywhere where #PCDATA, %block;, or %inline; are
  allowed:
We should make this more accurate by appending:
  (except as a descendant of any "out-of-line" formatting
  objects)

22. In 6.3, we say:
  multi-switch   The fo:multi-switch is used to switch 
    between two or more sub-trees of formatting objects.
This is not as clear as possible given the role of 
fo:multi-toggle in switching from one fo:multi-case to 
another.  Maybe a better wording would be:
  multi-switch   The fo:multi-switch wraps the specification
    of alternative sub-trees (each within an fo:multi-case)
    of formatting objects and controls the switching (activated
    via fo:multi-toggle) from one alternative to another.

23. In 6.3, we describe multi-case as:
  multi-case   The fo:multi-case is used to embed flow
     objects, that the parent fo:multi-switch can choose
     to either show or hide.
But that makes it sound like a multi-switch could show
3 cases and hide 4 which is not the case.  Suggestion:
  multi-case   The fo:multi-case is used to contain
     (within an fo:multi-switch) each alternative
     sub-tree of formatting objects among which the
     parent fo:multi-switch will choose one to show.

24. In 6.3, our current description of table-caption reads:
  table-caption   The fo:table-caption formatting object
     is used to contain block-level formatting objects
     containing the caption for the table.
As written, I fear people will think they must use this
FO to get a caption on any table; however, in fact this
FO is only allowed within fo:table-and-caption.  Therefore,
I think it would clear things up to augment the description
to read as follows:
  table-caption   The fo:table-caption formatting object
     is used to contain block-level formatting objects
     containing the caption for the table when using the
     fo:table-and-caption.

25. In 6.4.1.2 Page-masters, second para (typo):
  The page-viewport-area is defined by the output medium;
  the page-area holds the page contents and has the affect
  of positioning the page contents on the output medium. 
Change "affect" (which is a verb) to "effect" (which is 
the noun).

26. In 6.4.10 fo:repeatable-page-master-alternatives, the last
sentence before "Contents" reads:
  If the conditions on all alternatives to extend a sub-sequence
  are false, then the sub-sequence may not be extended.
I have no idea what this means, and a search for the word
"extend" in what seemed like a similar context failed.  This
needs to be reworded to avoid the word "extend" or to explain
what it means.

27. The example in 6.5.1.1.1 Chapter and Section Titles, Paragraphs
isn't quite right.  The input file and stylesheet don't really
quite generate the result tree shown, and the input file isn't
right for the discussion about spacing that follows it (e.g.,
"Space between the second paragraph of the first section and 
the title of the second section...", but the input file shown
has two chapters but never two paragraphs in one section).  
I've attached an HTML version of a corrected section 6.5.1.1.

28. In 6.2, under Trait derivation, we say "The half-leading 
trait is set to 1/2 the computed value of the line-height 
property minus the font-size property."  The "implicit
parens" in that mathematical expression are ambiguous.  I
suggest instead "The half-leading trait is set to 1/2 the 
difference of the computed value of the line-height property 
and the font-size property."

29. In 6.6.5 fo:external-graphic, under common usage, we say
"The fo:external-graphic flow object is used for an inline graphic
where the graphics data resides outside of the fo:element tree."
I'm not sure what to suggest, but the use of the term "inline
graphic" in this sentence can be confusing, since we're talking
about external graphics (residing outside the tree).  The problem
is that there are two uses of the term "inline", but I fear some
readers will get confused by "external inline graphics".  Maybe
even just saying "inline-level graphic" if that works, or something
else--I don't know.

30. In 6.6.5, we don't mention about wrapping fo:external-graphic 
in fo:block to produce a display graphic (though we do have such
an example)--we do say the analogous thing for leaders and 
simple-links and such, so I recommend we add a Note saying:
  An fo:external-graphic can be wrapped in an fo:block to create 
  a display graphic.

31. In 6.6.6 fo:instream-foreign-object, under Constraints, we
say "See [6.6.5 fo:external-graphic]", but then under Contents,
we repeat all of what was under Constraints in 6.6.5.  I think
what should be done is to move the 3rd para onwards from contents
to constraints and to remove the reference to 6.6.5.

32. In 6.7.3 fo:table we say:
  inline-progression-dimension="auto" table-layout="fixed" 
  The automatic table layout shall be used.
This has been the discussion of some email from Norm et al.
This has to change to say "The fixed table layout shall be
used" to make sense and for CALS tables to work.  It is
an absolute requirement for me that XSL support the composition
of CALS/OASIS Exchange tables.

33. In 6.7.5 fo:table-caption, I have the same comment here as
I did in comment 20 above.  We should reword the common usage
to read:
     The fo:table-caption formatting object
     is used to contain block-level formatting objects
     containing the caption for the table when using
     the fo:table-and-caption.

34. In 6.7.10 fo:table-cell, I was surprised not to see any
discussion of starts-row and ends-row.  I realize these are
properties and, as such, are discussed in section 7, but I
think some mention of them in this section would be helpful.

35. In 6.8.1.1.1 Numbered List, the second para says:
 The style is to number the items alphabetically with a
 dot at the end of the number.
however, I think most people will be confused by the phrase
"numbered alphabetically" (I know I was).  An acceptable phrase 
would be "enumerated alphabetically", so I suggest changing 
the sub-section title to "6.8.1.1.1 Enumerated List"
and the second para to "The style is to enumerate the items 
alphabetically with a dot at the end of the letter."

36. In 6.9.1.1.2 Expandable/Collapsible Table of Contents,
the input example includes:
  xlink:href="http://w3.org/TR"
which has the wrong URL for the purposes described.  Although
it is just an example, it would be best to correct it to read:
  xlink:href="http://www.w3.org/TR"
Likewise later in the XSL stylesheet for the same example and
in the result instance (total of 3 occurrences).

37. In 6.9.2 fo:simple-link, the note reads:
  An fo:simple-link may be displayed by enclosing it in an fo:block.
I fear the phrase "be displayed" is easily misinterpreted, so it
might be better to reword this to be something more like:
  An fo:simple-link can be wrapped in an fo:block to create 
  a display area.
(which is a bit more like what we said for fo:leader).

38. In 6.9.3 fo:multi-switch, under Trait derivation, we say:
  The currently-visible-multi-case trait has as initial value
  a reference to the first fo:multi-case child that has a
  value of "show" of the starting-state trait. If there is
  no such child, it has a value indicating that there is no
  currently visible fo:multi-case. The trait value may be
  changed by actuating an fo:multi-toggle. 
My question is, if there is no multi-case child showing at
all, then how can one actuate any fo:multi-toggle, as it
seems to say with the last two sentences above. 
I suggest the following rewording:
  The currently-visible-multi-case trait has as initial value
  a reference to the first fo:multi-case child that has a
  value of "show" of the starting-state trait; if there is
  no such child, the trait takes on a value indicating that
  there is no currently visible fo:multi-case.  When any
  fo:multi-toggle that is a child of this fo:multi-switch
  is actuated, this fo:multi-switch's currently-visible-multi-case
  trait value changes to refer to the fo:multi-case referred
  to by the actuated fo:multi-toggle's switch-to trait.

39. In 6.9.5 fo:multi-toggle (under constraints) we say:
 Activating an area returned by an fo:multi-toggle causes a
 change to the value of the currently-visible-multi-case of
 the closest fo:multi-switch.
I think we should be more specific and say something like:
 Activating an area returned by an fo:multi-toggle causes
 the value of the currently-visible-multi-case trait of
 the parent fo:multi-switch to refer to the fo:multi-case
 selected via this fo:multi-toggle's switch-to trait.  (See
 [7.30 "switch-to"] for how the switch-to value selects an
 fo:multi-case.)

40. In 6.11.3 fo:marker, we don't say that fo:marker has to 
be an initial child of its parent.  We mention this everywhere
else we talk about fo:marker, but it seems worth mentioning
it in this section too.  

41. In 7.3.1 "source-document" we say the value is:
  A list of space-separated URIs, indicating the XML
  document(s) used as input to the stylesheet.
and add:
  This property provides a pointer back to the original
  XML document(s) used to create this formatting object tree.
The "applies to" says "see prose", but I don't see in the
prose where we say anything about what FOs it applies to
(I assume it could apply to any FO).

I have two concerns:  (1) that this wording will imply that
there is special XSL semantics with this value, either in terms
of automatically setting a value for this property or in terms
of validating the value, and (2) that the "pointer back"
wording combined with "URI" will leave some readers thinking
that this points back to the source element as opposed to the
source document.  In fact, although we say that this value is
a URI, and not a URI reference.

So I'd like to see some added wording such as:
 This property can be used by the stylesheet writer to provide
 a pointer back to the original XML document(s) used to create
 this formatting object tree, but that this is not validated by and
 has no inherent standardized semantics for any XSL processor.

42. In 7.6.2 "background-color", we say that XSL adds icc-color
as a value of this property, but then there is no link to more
discussion, and it seems there should be one to 5.9.2 Color Functions.

43. In 7.13.1 "hyphenation-keep", we list the initial value as
"none", but that's not a value choice--I think we mean "auto" here.

44. In 7.13.10 "text-align-last", the value <string> says it:
  applies only to table cells. If set on other elements, it will 
  be treated as "start".
This isn't right, and in fact, I don't believe the <string>
value is well defined or necessary, and I suggest we remove
it from this property.

45. In 7.15.1 "color", we mention icc-color, but don't include a
"see also" link there to 5.9.2 Color Functions as we probably should.

46. In 7.30 "switch-to", under xsl-preceding, we say:
  Activating the switch should result in that the current fo:multi-case
  is replaced by its preceding sibling.
Odd wording there "should result in that"?

Also, the last sentence here just before xsl-following starts with
"It" when it should start with "If".

Also, the same two comments apply to the xsl-following description.

47. In 7.34.6 "empty-cells", near the bottom of the CSS box, there
is a mention of &&nbsp; where two &'s show--typo.

48. In 7.36.6 "score-spaces", both "applies to" and "percentages"
says "see prose", but there is nothing in the prose.