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(_at_)CraneSoftwrights(_dot_)com
Legal business disclaimers: http://www.CraneSoftwrights.com/legal
--~------------------------------------------------------------------
XSL-List info and archive: http://www.mulberrytech.com/xsl/xsl-list
To unsubscribe, go to: http://lists.mulberrytech.com/xsl-list/
or e-mail: <mailto:xsl-list-unsubscribe(_at_)lists(_dot_)mulberrytech(_dot_)com>
--~--