RE: [xsl] Diagramming XSLT

["Earley, Jim" <Jim.Earley@xxxxxxxxxxxxxxxxxxxxxx>]

Wendell pretty much hit the nail on the head.  I've had the opportunity to
explain XSLT to very interested, bright Java developers who understand
imperative programming models yet find it difficult to grok the declarative
nature of XSLT.  Here's what how I approached it (your mileage may vary):

To start, I set the foundation that everything in XML (elements, text, PI's,
comments, attributes) is a tree node that can be traversed.  After
establishing that, I basically used the metaphor that each template match
could be metaphorically treated as event handlers/listeners that could be
fired when a the XSLT processor traversed any particular node in the tree. I
used the notion of private methods to describe named templates that could be
called from within the "event handler" match templates.

While this isn't entirely accurate and only scratches the surface to the full
power of what XSLT can do, it did help bridge the gap for the folks that had
the hardest time with XSLT, without bogging down in the intricate aspects of
XPath and context.  What this did is to let folks dip their toes in the water,
before diving in head first.

I was fortunate to have a audience with a common foundation that I could talk
to, and that all understood a common programming metaphor.  Not knowing your
audience, this approach may not apply at all, but hopefully it might spark
some ideas.


----------
Jim Earley



-----Original Message-----
From: Wendell Piez [mailto:wapiez@xxxxxxxxxxxxxxxx]
Sent: Tuesday, April 08, 2008 12:38 PM
To: xsl-list@xxxxxxxxxxxxxxxxxxxxxx
Subject: Re: [xsl] Diagramming XSLT

James,

I have lots of experience of this sort, plus I know people with similar
experience, among whom this is an interesting topic for conversation, debate
and war stories.

In my experience, what you are asking can be challenging, since it has to be
calibrated very carefully to the level of your audience. An expert, patient
and interested audience will do better than an inexpert, impatient and
uninterested audience. But these qualities do not always go together. Plus,
"expert" is a problem, since some audiences that believe themselves to be
expert are expert in something less relevant than they think. (And this can
lead to impatience.)

Even prior XSLT expertise can be a problem with people who have gotten off on
the wrong foot.

Then there are mixed audiences, which are especially challenging.

My advice there is to aim at the most patient and most interested, which is
often the least expert. You can speak to a "beginner" or near-beginner level
without speaking down to anyone -- partly since the most expert tend to know
that rebooting one's brain to "beginner"
state is one of the most expert things one can do. :-) The best results come
when you can connect with the beginners without leaving the experts out -- or
if you like, connect with the expert audience without leaving the beginners
behind. If the most expert are interested even in what you're telling the
beginners, they will lead the others.

As for how to approach it, if what you're trying to get across is the
processing model and the basic notion of matching templates and generating
results, diagrams may actually be a hindrance, since the "flow" of the
stylesheet as it matches one node and then another is going to be quite
complex on anything but the most trivial and unrepresentative cases. People's
brains don't recurse well past about four levels without help (even those of
us who like the idea of recursion). We're much better with iteration.

On the other hand, I have had good results displaying a step-by-step debugger
as it works through applying a stylesheet, such as the one that comes in
oXygen. Even here, some attention has to be given to the source document,
since it needs to be simple enough for transparency, but complex enough to be
plausible (which is to say nearly "realistic"). Start with just a very few
templates, and include copies of the built-in templates so their operation is
not hidden. (This is important.)

As for static diagrams illustrating the processing model, this is tough. I've
seen many, but none that don't have weaknesses to go with their strengths. (If
anyone has any candidates I'd love to see them.)

The real message, however, is in the conceptual bridge between why XSLT works
this way, what's it good for, why this is a strength not just something really
strange, and so forth. For those purposes, good examples especially showing
code can help. A short stylesheet that does a graceful job of rendering a deep
and shaggy source document can tell volumes all by itself (especially to those
who've already struggled with similar problems).

But again, how you build this conceptual bridge between the design of the
language, and its nature as a strategic asset to managers and developers at
all levels, is very sensitive to who your audience is, to their mindset,
expectations and disposition.

I hope others contribute to this thread: it's interesting.

Cheers,
Wendell

At 12:14 PM 4/8/2008, you wrote:
>I'm preparing a conference talk, and in part of that talk I will be
>explaining the functioning of an XSL transform to an audience of mixed
>XSLT expertise.  I was thinking that a flowchartish diagram would help.
>I'm not looking to diagram every single template, just give a broad
>overview - stuff like "the output from the "gentext" mode templates is
>saved in this variable and then processed by the default-mode
>templates."
>
>Are there any good examples of this sort of XSLT diagram on the web?
>Does anyone attempted this before and have any advice?
>
>Thanks,
>
>-James
>
>-----
>James Sulak
>Electronic Publishing Developer
>Jones McClure Publishing


======================================================================
Wendell Piez                            mailto:wapiez@xxxxxxxxxxxxxxxx
Mulberry Technologies, Inc.                http://www.mulberrytech.com
17 West Jefferson Street                    Direct Phone: 301/315-9635
Suite 207                                          Phone: 301/315-9631
Rockville, MD  20850                                 Fax: 301/315-8285
----------------------------------------------------------------------
   Mulberry Technologies: A Consultancy Specializing in SGML and XML
======================================================================