Re: [xsl] mode

Subject: Re: [xsl] mode
From: "G. Ken Holman" <gkholman@xxxxxxxxxxxxxxxxxxxx>
Date: Thu, 14 Apr 2011 16:40:06 -0400
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

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:

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:

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.
G. Ken Holman                 mailto:gkholman@xxxxxxxxxxxxxxxxxxxx
Legal business disclaimers:

Current Thread