- From: Susan Lesch <lesch@w3.org>
- Date: Wed, 21 Feb 2001 22:40:56 -0800
- To: xsl-editors@w3.org
These are comments for your XSL 1.0 Candidate Recommendation [1] "work in
progress," based on one reading. It is a beautiful piece of work. Most
likely I missed a few things, and hope to read this again when/if it
reaches Proposed Recommendation.
General
-------
There appears to be a glitch in a production script or DTD that is adding
unneeded table markup in the form of default and empty HTML attribute values.
For example, there are over 5000 occurrences of "rowspan="1" colspan="1"
align="left"." Removing extraneous table markup will cut the HTML version
by 15%, from 1.5 down to 1.2MB (more than 25% for section 7 alone).
Chapter 2, Introduction to XSL Transformation, has little to do with XSLT
and a lot about Namespaces in XML. Should this chapter have a new title?
I would save 10k and omit 6.3 Formatting Objects Summary, since this
information is repeated on the same page.
In the 7.2 table, the top row should be th elements to meet level-A Web
Content Accessibility Guidelines; (see checkpoint 5.1 on
http://www.w3.org/TR/WAI-WEBCONTENT/#gl-table-markup).
<th>Box</th><th>Area</th>
Colors as well as border widths would help to differentiate the three kinds
of property descriptions in section 7. (I'm not certain that they need to
be differentiated at all since they are labeled, but was mildly confused by
the presence and absence of two different yet similar black borders.)
Globally
--------
Reserved words like fo and property names, datatype names, units and
boolean values are sometimes plain text, sometimes in double quotes,
sometimes in single quotes, sometimes in angle brackets, sometimes bold,
and once in a while monospace. (Some of these treatments come from CSS2.)
It's a big job to change them all, but it would help the reader if you
could establish and stick to a pattern.
"White space" is two words. DSSSL has it as one word, and Merriam-Webster,
American Heritage, and XML give it as two. (See
http://www.w3.org/TR/REC-xml#sec-white-space.) "Word space" and "letter
space" are two words also, and not hyphenated.
Globally and in particular in 7.14.7 "linefeed-treatment", line feed is two
words; (see http://www.unicode.org/charts/PDF/U0000.pdf). Maybe this
property should be named line-feed-treatment. Also, in 7.14.8,
ignore-if-before-linefeed -> ignore-if-before-line-feed, etc.
As far as I know, user agent is not a proper noun. Throughout the spec, it
is most often capitalized, sometimes not. It could be lowercase always, or
always one way or the other.
When referring to a W3C Recommendation, "Recommendation" is capitalized
(following Process Document usage, see
http://www.w3.org/Consortium/Process/).
Mentions of the Unicode bidirectional algorithm need to be uniform. Maybe
these notes will help. Unicode is capitalized and the other two words are
not. UAX#9 has two occurrences of "BIDI" and none for "bidi." So, for its
first occurrence, say
Unicode bidirectional (BIDI) algorithm
and then
Unicode BIDI algorithm
or else spell out the whole name each time.
Images
------
If there is time, could all the images match? For example in section 4 they
look like the work of a few different people.
In sections 1, 4, 6 and 7, all images need alt text and real rather than
GIF text so that people who cannot see the illustrations can follow.
Section 7 looks good and may need only minor changes. Here's one way, for
section 1.
<div class="image">
<p class="caption">XSL Two Processes: Transformation and Formatting</p>
<p><img src="two-process.gif" alt="Diagram of XSL conceptual model, showing
a source tree, a result tree with element and attribute nodes, and XSL
formatters including a printer, a cell phone, and a Web browser."></p>
<p class="explanation">The result tree is the result of XSLT processing.</p>
</div>
In 4.10, in the sample area tree image, letter spacing is off and some text
is covered. Could this image (page-area-tree.gif) be fixed? Some labels in
japaneseblock3.gif in section 4.2.3 also have minor letter spacing
problems. In 6.4.1.6, the top of the top "f" and the right side of the
right-hand "w" are missing.
In 6.4.12, the vertical labels are unreadable in the peach colored part of
PageAndRegion-bodyWithOrientationOnPage.gif (third image). Otherwise, this
is a really nice diagram.
References
----------
You might alphabetize references.
In "W3C XML," "W3C XML Names," and "W3C XML Stylesheet," why say "W3C" in
the short name of some and not all W3C references? W3C can be omitted.
In D.1, XML 1.0 is of course now in its second edition, and "See
http://www.w3.org/TR/1998/REC-xml-19980210" can read "See
http://www.w3.org/TR/2000/REC-xml-20001006".
In D.2 W3C XML Stylesheet
W3C Working Draft. See http://www.w3.org/TR/WD-xml-stylesheet
becomes:
W3C Recommendation. See http://www.w3.org/TR/xml-stylesheet/
In D.1, the citation would be:
Unicode Standard Annex #9: The Bidirectional Algorithm
(see http://www.unicode.org/unicode/standard/versions/)
In D.2, UNICODE TR10 is Unicode Technical Standard #10 (a UTS rather than
UTR and no longer a draft).
In D.2, UNICODE TR20 is Unicode Technical Report #20 (no longer a draft).
Also for the three Unicode references, index.html can be cut from the URI.
For 7.8.1, 7.8.2, 7.28.24, and D.1, the reference can be RFC 3066; (RFC
1766 is obsolete). See http://www.ietf.org/rfc/rfc3066.txt.
RFC 2119 can be a normative reference, and section 8 could say:
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
[RFC2119].
Please see RFC 2119 at http://www.ietf.org/rfc/rfc2119.txt. If you don't
want to use the RFC, those words need definitions if used in section 8.
Minor typos
-----------
From here down, a section number is followed by a quote and then a
suggestion.
Authors and Contributors
ArborText
Arbortext
Status of this document
encourges
encourages
1.2.1
XPath (first occurrence)
<a href="sliceD.html#XPATH">[XPath]</a>
1.2.1 par. 5
line-feeds
line feeds
1.2.5 last par. (they are dictionary words)
used for sub- and super-scripts
used for sub- and superscripts
4.2.2 last list item needs closing parenthesis.
5.2 Note (first occurrence of conformance) and 7.28 par. 1
Shorthands are only included in the highest XSL conformance
level: "complete".
could link to <a href="slice8.html">[8. Conformance]</a>
5.8 par. 2
based on both of an implicit part
based on both an implicit part
5.8 par. 4
UNICODE TR-9
Unicode Standard Annex #9 or UAX#9 or [UNICODE TR9] (not sure which is best
but I don't think it's hyphenated)
5.8 last Note
spliting
splitting
5.9.6 last par.
value of property
value of a property
5.9.7 needs an ending period.
5.9.9 (link needed at first occurrence)
Only RGB (Red, Green, Blue) and ICC (International Color Consortium)
Only RGB (Red, Green, Blue) [sRGB] and ICC (International Color
Consortium) [ICC]
(adding a new reference, http://www.w3.org/Graphics/Color/sRGB.html)
5.11 <uri-specification>
URI-reference
URI reference
6.3 bidi-override
Unicode-bidirectionality algorithm direction
Unicode-bidirectional-algorithm direction
6.4.4 par. 3
function[5.10.2 Color Functions]
function [5.10.2 Color Functions]
6.4.4 list item 2
sRGB
Needs a link to references [sRGB].
6.4.7 Constraints
Note that the mapping of sub-sequences of the sequence
of pages to sub-sequence-specifiers need not be onto;
^
(I wasn't sure if "onto" meant one to one.)
6.4.10 Constraints
the sub-sequence of pages consist
the sub-sequence of pages consists
6.4.19 Constraints
if P is a page-reference-area C is an area-class, and
if P is a page-reference-area, C is an area-class, and
6.5.2 Note after Trait Derivation:
uasge
usage
6.6.3 par. 4
Unicode Special-use tag characters
Unicode special-use tag characters
(see http://www.unicode.org/unicode/reports/tr7/index.html)
6.6.3 Constraints
The dimensions of the area is
The dimensions of the area are
6.6.5 last Note
For example, using a size of 1/96" as the size of one pixel for rasterized
images. is an incomplete sentence.
6.6.7 Contents
a descendant an fo:leader
a descendant of an fo:leader
6.7.1.1.1 par. 1
specificed
specified
6.10.3 Constraints par. 3
fo:foonote
fo:footnote
6.11.1.1
the "code" elements are using a Courier font
the "code" elements using a Courier font
7.3.1 second to last par.
W3C Accessibility guidelines
W3C accessibility guidelines (which ones? Can you link to them?)
7.3.2
An URI-specification
A URI-specification
7.3.2 second to last par.
(QName [W3C XML Names]
Needs a closing parenthesis.
7.7.1 par. 8
Far-Eastern (twice)
Far Eastern
(not sure eastern and western have global meaning either)
7.7.1 caption for second illustration
EM Box
EM box
Example 4
example 4
7.7.4 last par.
rounded the nearest whole pixel
rounded to the nearest whole pixel
7.7.7 backslant and 7.7.8 second to last par.
(http://www.w3.org/TR/REC-CSS2/fonts.html#algorithm")
(http://www.w3.org/TR/REC-CSS2/fonts.html#algorithm)
7.12 par. before last illustration
super-script (or sub-script)
superscript (or subscript)
In 7.20.4, ending double quote can be cut.
7.21.2 Note
sub-title
subtitle (It's a dictionary word. Not sure that is what is meant.)
7.24.8 media:
viaual
visual
7.24.10 bounded-in-one-dimension second par. can have an ordered list:
...There are four cases:
1. the "reference-orientation" is "0" or "180" and the
"writing-mode" is horizontal;
2. the "reference-orientation" is "0" or "180" and the
"writing-mode" is vertical;
3. the "reference-orientation" is "90" or "270" and the
"writing-mode" is horizontal;
4. the "reference-orientation" is "90" or "270" and the
"writing-mode" is vertical.
For cases 1 and 3, the "page-width" is bounded and the "page-height" is not
bounded. For case 2 and 4, the "page-height" is bounded and the
"page-width" is not bounded....
7.24.12 and 7.24.14 auto:
continous
continuous
A fallback to 11.0in would fit on both 8+1/2x11 and A4 pages).
A fallback to 11in would fit on both 8 1/2 x 11 and A4 pages.
(not sure there)
7.26 Note list item 2
Table
table
7.26.4 use-font-metrics
dominat
dominant
7.26.5 <length>
domiant
dominant
7.26.7
please see the "Internationalization Appendix".
please see <a href="sliceA.html">[A Internationalization]</a>.
7.28.13
"smallcaption"
small-caption or small caption
In B.7, there's an extra period after the aural fallback.
C.1 Refine
Refinement
refinement
[1] http://www.w3.org/TR/2000/CR-xsl-20001121/
Best wishes for your project,
--
Susan Lesch - mailto:lesch@w3.org tel:+1.858.483.4819
World Wide Web Consortium (W3C) - http://www.w3.org/
Received on Thursday, 22 February 2001 01:41:19 UTC