Re: DSSSL Documentation Project?

[christo@xxxxxxxxxxxxxxxxxx (Frank Christoph)]

> The text of the standard is useful to you, but I'm postulating that
> there are people starting out with DSSSL who want something simpler
> with more hand-holding than the precise wording of an International
> Standard.

"Hand-holding" is a really awful word.  The first time I saw it used
in this context was when I read the GNU manifesto, and even though I am
mostly in agreement with Stallman's idea of free software, he really
turned me off with that word.  When you design something with the intent
that it be used by others, it is your responsibility to explain it, and
furthermore to do so in a clear and succinct manner, with an ear for your
audience: the designer becomes a teacher, and the users become students.
But when you use the word "hand-holding", you are shirking that
responsibility; you're saying in effect, "You don't get it?  Well, maybe
you should just try a little harder, you twerp."

Now, you claim that the wording used in international standards is precise.
I will give you that much.  It is pretty much as precise as vulgar speech
can be.  But it is certainly neither clear nor succinct.  Let me give you
two representative examples from our favorite ISO standard.

  The parts from a sequence of process specification elements consist of
  the sequence of parts from the first process specification element,
  followed by the sequence of parts from the next process specification
  element, and so on.  [7.1]

I had to read this about three times before I even got an inkling of what
it means, and then at least once more to figure out that it was not just a
tautology, but a definition of something called "sequence of process
specification elements".

  For each property assignment of a node, there is a unique corresponding
  property of the node's class whose name is the same as the name part of
  the property assignment.  This is referred to as the property of the
  property assignment.  The value part of a property assignment is referred
  to as a value of the property of the property assignment.  [9]

Here, the definition of terms is clearly indicated, but the redundancy,
repetition and overloading of words makes it very difficult to follow.
(Overall, though, I actually think the section on nodes is one of the clearest
parts of the standard---except for that abomination, the "origin-to-subnode"
relationship, and the forty or so pages of raw SGML text defining the
SGML property set [9.6].)

When we teach mathematics or computer science, and even engineering, in a
classroom, and when we write textbooks for these subjects, we don't write
things this way.  Definitions, propositions and theorems are clearly marked,
so the reader can easily distinguish between what is being defined, claimed
and proved; we (sometimes ab)use concise formal notation, in particular
named variables, to indicate coreferences ("Jack" and "his" in, "Jack forgot
his jacket") and identity, and to avoid redundancy and verbosity; we include
exercises and examples to help the reader help himself, and to emphasize
important points.  This style of teaching has developed over the course of
3000 years, and we still use it develops difficult ideas in a concise,
unambiguous and understandable manner.

Now, I understand that an international standard is supposed to be widely
accessible, and I understand the value of natural language presentations.
But, as we are often reminded, formal notation is intended to help, not
hinder, us, and mathematics is a language even more universal than ISO
English.  And even the most rigorous mathematician augments formal
developments with textual explanations---it's not an either-or situation.

Anyway, it is one of my long-standing gripes that when we start talking
about computers and programming, we abandon traditional formal methods
because of some vague feeling that a computer is real and concrete, a
tool for the proverbial everyman, whereas mathematics is some abstract
and mystical Platonic ideal steeped in the misconceptions of academics
who are out of touch with the Real World---and then we turn around and
embrace pseudo-science like object-oriented "methodologies" and the
unarguably idealistic notion of "language-neutral" bindings.  IMHO, if
a concept is difficult or complex, and the formal statement of the concept
is also complicated, then most probably the equivalent statement in
natural language will either be ambiguous or even more complicated, and
neither ambiguity nor unnecessary complexity has any place in a standard
or a specification.

Well, I know I am just pissing in the wind here anyways, so I will stop
rambling and talk about what everyone else wants to talk about.

I am certainly in favor of more documentation for DSSSL, hand-holding or
whatever you want to call it.  I know I've been mystified on several
issues, some of which have been cleared up since I discovered this list;
I am sure there are many others who have not been so lucky.  I think
John Fieber's outline is an excellent place to start.  I would also like
to see some subject-oriented (as opposed to task-oriented) explications
of parts of the standard, i.e., answers to the question, "Why is this here?
What is the point of this?"  For example, what is the point of:

  * generated text?

  * glyph ids?

  * styles?

  * processing modes?

  * the transformation language?

  * decoration areas?

  * anchors?

Or,

  * What is the difference between a quantity, a length-spec, an inline space
    and a display space?

These are not beginner's topics, I suppose, but it can be difficult to grasp
the standard as a whole without understanding at least the purposes of the
features.  Also, I think the average person will be unfamiliar with some of
the typesetting jargon (I know I am).  As some simple examples, what is

  * a spread?

  * a sideline?

  * a line-field?

  * a leader?

  * kendot scoring?

And, of course, lots of examples.  I saw a book on TeX once, where all the
left pages were TeX code, and all the right pages were the formatted results.

---
Frank Christoph                 Next Solution Co.      Tel: 0424-98-1811
christo@xxxxxxxxxxxxxxxxxx                             Fax: 0424-98-1500

 DSSSList info and archive:  http://www.mulberrytech.com/dsssl/dssslist