Re: [xsl] mode

["G. Ken Holman" <gkholman@xxxxxxxxxxxxxxxxxxxx>]

At 2011-04-14 22:13 +0200, Imsieke, Gerrit, le-tex wrote:
> On 2011-04-14 21:47, G. Ken Holman wrote:
> > Namespaces in libraries avoid execution errors and duplicate declaration
> > errors.
> >
> > Very useful. And this approach has been available since day one of XSLT
> > 1.0 and so has been a long-time practice for me. I first started using
> > it when contracted to create a library being sent out of the development
> > team to many remote departments who were going to have their own
> > developers write importing stylesheets.
>
> ...
> This is actually a good use case for justifying the much-contested 
> XML namespaces.

I have been a *big* fan of XML namespaces from the start.  In the 
classroom I try to convey to students how very useful they are, and 
how they are worth the effort.

Note that I include this two-namespace "stylesheet writing rule" in 
my XSLStyle stylesheet for stylesheets:

  http://www.CraneSoftwrights.com/resources/#xslstyle

I can designate in the stylesheet that namespace to use as the global 
namespace (your term of "API namespace") and that namespace to use as 
the internal namespace.  Then, only the API global variables are 
listed at the start of the documentation (all global variables are 
listed in the alphabetized index at the end of the documentation 
along with all named top-level constructs).

Some teams impose check-in constraints such that the stylesheet being 
checked-in to the source code control system has to first pass 
through XSLStyle without any detectable inconsistency errors in 
Crane's stylesheet writing rules.  Of course any team can tweak what 
I've done with their own rules since the stylesheet isn't obfuscated.

Note that many stylesheet writers *hate* that this requires, among 
other rules, *every* top-level construct to be documented, and 
*every* parameter of *every* template rule to be documented, and 
*every* global variable, global parameter and local parameter to be 
constrained with an as= type.  But if they could get around the extra 
typing involved, they should realize that imposing these writing 
rules makes for a better stylesheet before debugging even begins.

Writers have the choice of DocBook, DITA or XHTML for the embedded 
documentation.  The XSLStyle vocabulary is used as the scaffolding in 
the XSLT stylesheet in which the documentation vocabulary is used.

CSS stylesheets can be used to format the result.  An example 
XSLStyle documentation result that has been made publicly visible is here:

  http://sportsmlt.svn.sourceforge.net/viewvc/sportsmlt/2.0/sportsmlt2.html

That shows the table of contents, the import/include tree, the 
top-level constructs and the alphabetized index.  The embedded 
documentation vocabulary is DocBook for that example.  Public and 
private namespaces are used (thus distinguishing the one available 
specialization parameter from all the other module globals).  Note 
that this wasn't developed a library, but using the library 
conventions in the writing rules means that at any time one can use 
it as a library simply by wrapping it with an importing stylesheet.

. . . . . . . . . . Ken

--
Contact us for world-wide XML consulting & instructor-led training
Crane Softwrights Ltd.          http://www.CraneSoftwrights.com/s/
G. Ken Holman                 mailto:gkholman@xxxxxxxxxxxxxxxxxxxx
Legal business disclaimers:  http://www.CraneSoftwrights.com/legal