Comments:

To:   xsl-editors, sdeach@adobe.com

Comments:
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.
DaveP
AC member, RNIB.



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

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

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
intent
of the notes. If so, make a clear statement to that effect
early
on and make broader use of it.



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

para 2.
Tree construction, for someone not from the DSSSL background
is
totally new. Since you reference definitive documentation,
could
you put in a laymans description of why and what, followed
by
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
rather
than usage. Brief statement of what they are before the
implementor
definitions please. Perhaps take the line given in the 'box
model
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
account
of the terminology used here. At least for the major items
which
you expect a new user to comprehend, if not the minor
elements.
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
is
needed.

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 4.1.1.1 third para.

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

para 4.1.1.3
This starts to make sense to the unitiate. Build to plain
English
and take it back up to the definitions of page sequence,
block
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
this
as the 'dummies guide' section? Unless you need it for
implementors)

para  4.1.7.1 Mmm. Needs some form of illustration? Totally
meaningless
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
4.1.7.2 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
paragraphs,
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
inline-included-container
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
masters
which dictate the overall layout of a document. It contains
the
page master definitions."

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

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
sentences
really needed? The fact that it <quote>generates a sequence
of
page-level area-containers. </quote> leaves me hanging. Tell
me that
it binds my text and graphics into the 'shapes' that I
specified,
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
front
page, a series of 'normal' type pages for each major
section, then
a special page for a section head? Your version is accurate,
terse,
mine tells a story that applies to a user. Is mine a valid
entry
in this document?

sequence-specifier-alternating. Now you are speaking my
language!
10/10.

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


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
Properties

Since this structure is used throughout 4.3.x, tell me why
each
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
approach.

The most common content of 'area type' is 'generates no area
directly'.
Skimmed through to 4.3.9 and still have no idea what its all
about.
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
is?

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
this
example and add to the 4.3 introductory matter being
indicative
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
whatever?

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
body
is filled with (your example) columns, which are filled with
text?

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
clouds
of confusion for me. A nice example would help, say a two
line
header with a company logo at one side, a chapter title and
a
page number?

Idea; To cater for lr-tb, why not cater to (my guess) the
majority,
and use simple English, defining the exactness by tagging it
with
lr-tb, which you can then explain in a single section. it
could
reduce your document by 15%?
E.g. <q>This region defines a viewport that is located on
the
"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
viewport
and the area-container?

4.3.14 fo:flow
Am I right in thinking this is pretty much 'heart of the
matter'
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
the
indirection. What purpose does it serve? It may not
'directly create an area', though surely the end result is
exactly
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
this
is important to the end user. Is it? If so, please elucidate
via
an example. Why might 'instances of regions' have the same
name?
How does the user specify any hierarchy?

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

Area type: Again your insistance that it does not directly
create
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
these
pretty early on in his/her usage of XSL, how about a simple
example?
My objective is to present the new user enough simple stuff
to
make a start (the XSL hello world?) without pain. How to
include
enough of this without making the reader plough through 10KB
of
implementor detail? primary objective: To gain user
acceptance of
XSL as a viable tool which is not overly intimidating for
simple
stuff.

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

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

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

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


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

4.5.2.
Common use. How to present from this, upwards towards pages,
to
'paint the picture' as to how these things fit together to
build
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
paragraph
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
example?

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

4.7.1. list-item-label. I'm guessing this might be a bullet,
but
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.
Please
   clarify

4.8.2 common use:
Please clarify the term 'visible at a single time'. Make up
your
own version of silly interpretations :-)
  very clear note. Would be nice to see a syntactic example
of
  usage, since this appears very new (to me). Perhaps to
represent
  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 :-(

4.9.1.
  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
earlier
  examples. The last two sentences are clear, but lack an
explicit
  example.


5.1
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
need
some way of making the more straightforward ones more
accessible
to the spec user. Sorry, no ideas at the moment.
Perhaps a simple statement of how a property is used in
combination
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
   inadequate.

   If this is going to make the document too big, then take
advantage
   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.

5.5.1.2
    Again, in support of the novice, please provide a simple
example
 of usage.

5.6.6.1  The phrase 'the language specified for the document
' is
used. Please clarify. Is this related to the author,
intended
target country, or what? Not very clear.

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

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

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

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

end of comments.

Received on Saturday, 10 July 1999 09:14:44 UTC