W3C home > Mailing lists > Public > xsl-editors@w3.org > July to September 1999


From: Dave Pawson <dave.pawson@virgin.net>
Date: Sat, 10 Jul 1999 14:16:16 +0100
Message-ID: <002b01becad6$6aa0ae80$47c3fad4@home>
To: "xsl Editors" <xsl-editors@w3.org>
Cc: <sdeach@adobe.com>
To:   xsl-editors, sdeach@adobe.com

Extensible Stylesheet Language (XSL) Specification
W3C Working Draft 21 Apr 1999

In answer to a request for an improvement in the
usefulness of the document. Posted XSL list,
8 July 1999.

I hope these comments are received in the spirit
in which they are sent.
I wish you well in a very difficult task.
AC member, RNIB.

1. Audience.
I understand its prime audience is the implementers.

Since this document is highly likely to be the only
material for some time for end users, I would like to take
stance and request additions / changes which would assist
group. Please take all my comments in that light.
How to identify content in the WD which is the a requirement
an implementor and seperate it from that information which
intended for the end user?

4.3.1 R: For the implementor stuff
4.3.2 I: For the end user.

I have used this form in software requirement documents,
where an
implementer SHALL respond to R: paragraphs, but I:
paragraphs are
informative, not a requirement.

In 4.9.2 the note content implies this has partly been the
of the notes. If so, make a clear statement to that effect
on and make broader use of it.

para 1.
Clear. Would be assisted if a simple end user processing
were given, both in text and graphically, as per ISO 10179.
This to show transformation from source XML through to
output media, indicating potential for an implementation.
Could you build on what is provided in 3.4 (formatting

para 2.
Tree construction, for someone not from the DSSSL background
totally new. Since you reference definitive documentation,
you put in a laymans description of why and what, followed
how used by an end user. (you do later, see 4.3.1)

para 3.4.2 the definitions are given in terms of content
than usage. Brief statement of what they are before the
definitions please. Perhaps take the line given in the 'box
diagram'? To show the relationships?

3.4.* To those not from the print industry, \Texers etc. the
terminology here is mystifying. Knuth illustrates this well
for Tex, (the texbook, chapter 11: boxes) showing the glyphs
building into areas which could be extrapolated to take
of the terminology used here. At least for the major items
you expect a new user to comprehend, if not the minor
Again build on 'Nominal and Maximum line rectangles' gif, to
identify the terms and make them more 'real'.

para 3.6 No statement to the end user why this information

para 4.1.1 An example showing two different page masters and
their use in page sequences would help make this 'real'. E.g
illustrate third para.

para last para
Since this is likely to be the first thing that an end user
need to write in his/her stylesheet, how about an illustrive
example of use?

This starts to make sense to the unitiate. Build to plain
and take it back up to the definitions of page sequence,
areas and area containers. (keep it away from James C :-)
(Or, since you have yet to write 4.1.2 to 4.1.7, why not use
as the 'dummies guide' section? Unless you need it for

para Mmm. Needs some form of illustration? Totally
to me as written. How might I use it?
E.g. (If its appropriate, I have no idea). I want to fit a
number of
footnotes on a page. I must borrow space from the page
dependent on
the number of footnotes. This is a conditional region.
Something along
those lines may be intrepreted as 'real' for a user. Shit.
On reading I see footnotes do not apply here. Is this idea
still valid?

4.2 At last. Simple English (who took the pen off James?)
Uprate this
section. This is the first mention of <quote>for formatting
titles, headlines, figure and table captions, etc. </quote>,
ie. things
that have meaning to a simple user. 10/10.
More work needed on display-included-container and
to bring the same clarity. How might they be used?
layout-master-set is what? Whats a wrapper? How about
"A layout-master-set is used to specify the set of page
which dictate the overall layout of a document. It contains
page master definitions."

multi-case ?? does it have any use to an end user? Please

multi-property-set ?? I read the definition. Still no wiser.
multi-switch ?? Ditto.
multi-toggle ?? Ditto.
page-sequence. Good. Nearly very good. Are the last two
really needed? The fact that it <quote>generates a sequence
page-level area-containers. </quote> leaves me hanging. Tell
me that
it binds my text and graphics into the 'shapes' that I
and I would be far more interested.

sequence-specification. Does this tell me how my document
will 'look'
when I flow my text and graphics? That it will have a blank
page, a series of 'normal' type pages for each major
section, then
a special page for a section head? Your version is accurate,
mine tells a story that applies to a user. Is mine a valid
in this document?

sequence-specifier-alternating. Now you are speaking my

(getting very picky)
simple-link. <quote>the start resource of a simple
Err, yes, so what? "simple-link represents the start of a
whose end is another location in this or another document,
as is
used in HTML ....." Relates to a technology I understand. If
want to look forward, use xlink terminology, but with simple
descriptions? I note there is a far clearer description in

static-content. How used please? Whats the difference (to
the user)
of flows and static content?

para 4.3.1 NOTE: This is what I want!
Distribution of content. This is not informative. why is it
interesting to know about the distribution of content?

Common use
Area type
Distribution of content

Since this structure is used throughout 4.3.x, tell me why
is interesting?
E.g. 4.3.5, 4.3.6 common use is good. I'd love these to be
expanded. The
title 'common' excludes exactness, hence allows the right

The most common content of 'area type' is 'generates no area
Skimmed through to 4.3.9 and still have no idea what its all
Not dissimilar to 'distribution of content'. I'm getting
more confused.

I guess its useful to link through to properties, but why
are you
telling me about them here if only to link to them?
How are these 'properties' of interest to the user?
Give me an example of the xsl:fo with some properties, e.g.
page height,
and I might begin to realise I do need to read these bits.

4.3.3 common use, last para. This obviously 'painted a
picture', why not be
explicit. It says little to me as is.

4.3.4 common use. Sorry, too JC speak for me. Simple english

4.3.8 common use. 5th use of the word viewport. Here it
makes sense.
Would you define it please, simply. " A perspective on a
part of a page"?

4.3.8 area type. A clear usage of 'properties'. How to take
example and add to the 4.3 introductory matter being
of usage, hence of iterest to the end user?

4.3.8 Trait derivation. 'Normal rules for determining the
values of traits'
Where might I find these? link please, or explain.

4.3.9 Common use. Where's the illustration to remind me that
this is
'the chunk in the middle of the page where my text goes', or

4.3.9 distribution of content.
<quote>An fo:region-body does not have any "content in the
usual sense"
to be distributed</quote>. Maybe factual, but for the
end-user its
a fact, despite the indirection? The 'snaking columns'
reference tells
me this.
Perhaps you could tell me this in the positive, that region
is filled with (your example) columns, which are filled with

4.3.10 Question. to the end user, is this what I use to say,
I want a header? Being so exact about lr-tb is creating
of confusion for me. A nice example would help, say a two
header with a company logo at one side, a chapter title and
page number?

Idea; To cater for lr-tb, why not cater to (my guess) the
and use simple English, defining the exactness by tagging it
lr-tb, which you can then explain in a single section. it
reduce your document by 15%?
E.g. <q>This region defines a viewport that is located on
"before" side of fo:region-body region.</q> becomes
This region defines the (lr-tb) header. Just a thought.

4.3.12 common use. <q>The fo:region-start formatting object
generates one viewport and one area-container. </q>
Its getting to me. What is the relationship between the
and the area-container?

4.3.14 fo:flow
Am I right in thinking this is pretty much 'heart of the
country? The common use section is way-out too brief.
If not needed here, it is certainly needed earlier to get
across the
idea of flow objects. Pretty please.

Area type: Again there is an insistance on the exactness of
indirection. What purpose does it serve? It may not
'directly create an area', though surely the end result is
that, despite the indirection.

Distribution of content: third use of the term 'flow-map'.
As yet
undefined. Is it important?

Distribution of content: third para. I get the feeling that
is important to the end user. Is it? If so, please elucidate
an example. Why might 'instances of regions' have the same
How does the user specify any hierarchy?

4.3.15 fo:static-content
common use: At last the fog clears (last sentance first
Promote to earlier in the document please. Any other uses?
Does that mean if I want the header to reflect the chapter
I should use flow object instead of static content?

Area type: Again your insistance that it does not directly
an area. Try the positive view. I'll shut up on that one
now, but
it is irritating.

Distribution of content: Third and fourth paragraphs. What
are the
implications here? Sounds like a dire warning, without
telling me
the consequences.

4.4.1 fo:block.
Common use: On the assumption that an end user will need
pretty early on in his/her usage of XSL, how about a simple
My objective is to present the new user enough simple stuff
make a start (the XSL hello world?) without pain. How to
enough of this without making the reader plough through 10KB
implementor detail? primary objective: To gain user
acceptance of
XSL as a viable tool which is not overly intimidating for

4.4.2. Note that the end user wants (or at least I do) to
put this graphic here. How to include that information in a
non-intimidating manner?

I note your handling of alt-text is unresolved. Please
prior to next WD. It is important for VI access.

4.4.3 Common use. Please inform us why it might be needed,
a simple example.

4.4.4 Perhaps quote examples of usage, seperating line or
(?) change bar?

Common use:
None stated. Presumably the pdf type scrollable? If not,
what is
its 'common use'?

Common use. How to present from this, upwards towards pages,
'paint the picture' as to how these things fit together to
a presentation unit of page or scrollable area?

4.5.3 Common use:
If this is the same as 'first-line-indent' then tell us so.
"Commonly used to present the first line of text of a
with a distinct appearance" etc.

4.5.6 Common use: Why? What's it for? Example usage would be
very much appreciated.

4.5.7  Is this to 'wrap' upright and italic text, for

4.5.8 Again, example please. Perhaps even combined with a
reference to a page number? (4.5.9)

4.7.1. list-item-label. I'm guessing this might be a bullet,
its not intuitively obvious. Please make clear. (Its in
4.7.4, but
I'm guessing this isnt' the first usage case?

4.7.4 Includes the definition(see comment, 4.7.1), too late.

4.8.1 Common use:
   Whats the implication of the note? Leaves us curious.

4.8.2 common use:
Please clarify the term 'visible at a single time'. Make up
own version of silly interpretations :-)
  very clear note. Would be nice to see a syntactic example
  usage, since this appears very new (to me). Perhaps to
  the example given? Particularly in light of the
intrigueing example
  given in the last para of the section.

4.8.5 Common use:
Please define 'property set' as used here. First usage.
Whats the relationship to property groups as in 5?
Is it as defined in 4.8.6? This is getting quite
irritatingly regular,
using a term, then explaining it later :-(

  Putting my WAI hat on.
  How to make these floats accessible? How to recognise that
they are
  there for users whose normal mode is sequential access.

  Common use: Not my version of common use, as set by your
  examples. The last two sentences are clear, but lack an

Since this section is user oriented, could the descriptive
paragraphs be collected earlier? I'm trying to put myself in
the position of the novice, trying to find the properties to
use with the fo: elements. I commented the same earlier. We
some way of making the more straightforward ones more
to the spec user. Sorry, no ideas at the moment.
Perhaps a simple statement of how a property is used in
with a flow object would suffice? That has not been stated
so far.

5.2.1 IMHO you jump in too quickly. What are these values
assigned to?
 Can I have an opening paragraph, perhaps with a dummy fo
and property,
 that explains how the properties are associated with fo's?
 Simply to set the scene for the next (how many?) pages of
the spec.

 5.2 general.
   In agreement with Sebastian R. The cross references to
CSS2 are

   If this is going to make the document too big, then take
   of the fact and start to group into managable chunks.

 5.3 Lovely to see the aural properties in from the start.
Thanks TV.
    But note the caution about floats.
    Again, in support of the novice, please provide a simple
 of usage.  The phrase 'the language specified for the document
' is
used. Please clarify. Is this related to the author,
target country, or what? Not very clear.

5.6.7 Script.
  I find your use of this word unclear. If you are referring
  documents from a certain locale, then I'm OK. Because of
  rigour applied to other terms, it could do with

5.7 Breaks.
For the novice: Please indicate why they are of interest.
classic of title and following text is probably sufficient,
well as forced breaks.

5.10.4  flow-name.
Description please. What are they all about? How might I use

5.15.1 Shouldn't this be start and end instead of left and

end of comments.
Received on Saturday, 10 July 1999 09:14:44 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Monday, 7 December 2009 10:59:49 GMT