[XSL-LIST Mailing List Archive Home] [By Thread] [By Date]

Re: [xsl] Embedding stylesheet documentation using other vocabularies (e.g. DocBook)

---

---

I'm supposing that the ability of hyperlinks to work is something
reserved for files of type xmlfile, which is set by the registry. Thus
if one had a problem with that in a file with extension .rss one could
set files with extension rss to be of type xmlfile

so in HKCR if .rss is xmlfile then ths techniue should work. however
(not 100% sure but I believe it to be so) I think this will cause the
file to be opened by internet explorer. a lot of people running some
other browser might consider that a bad thing if the ability to open
ie was set  by file extension.

On 10/21/05, G. Ken Holman <gkholman@xxxxxxxxxxxxxxxxxxxx> wrote:
> Here's a different twist on an old topic: documenting XSLT
> stylesheets.  But I haven't seen my technique being mentioned as done
> by others and I've been encouraged to put it in a condition to be shared.
>
> I privately showed peers at XML'2004 and XTech'2005 my technique for
> embedding arbitrary documentation vocabularies in an XSLT
> stylesheet.  I've done this twice since for customers, embedding the
> DocBook vocabulary in XSLT for one customer, and the Intelligence
> Community Metadata Standards for Publication (IC-MSP) vocabulary in
> XSLT for another customer.
>
> What I think is interesting about this embedding (and the reason I
> pursued it in the first place) is the ability to simply drag an XSLT
> stylesheet into Internet Explorer and have the embedded information
> displayed as formatted documentation in HTML.  If you do a
> View/Source you see the raw XSLT stylesheet.  Because of the
> recognition of a stylesheet association processing instruction, I
> document my stylesheets by adding an association with a stylesheet
> for stylesheets, so it is automatically recognized.  Using the
> node-set extension in XSLT 1.0 processors, I feed the transformed
> documentation in the arbitrary vocabulary back through imported
> template rules for the documentation vocabulary to produce the HTML
> that is seen on the screen.
>
> I used it for my small environments and stylesheet libraries and
> didn't think much of exploiting it until, in both my customer
> situations, I was working with very large import trees:  a single
> apex of an import tree linking together dozens of stylesheet fragments.
>
> Two things came to light when dealing with very large import
> trees:  (1) - how the heck does one find out where a particular
> top-level construct is declared in a set of 37 stylesheet fragments
> (the report produces an alphabetized index of all top level elements
> and the modules in which they are declared), and (2) - how to ensure
> there isn't namespace collision (I'm a big fan and user of
> namespace-qualified top-level construct names and modes in XSLT
stylesheets).
>
> A bonus is, with arbitrary logic available using XSLT, the ability to
> enforce "business rules" about XSLT stylesheets, for example: "thou
> shalt document each and every top-level construct and each and every
> <xsl:param> in an <xsl:template>" and "every name and mode declared
> in this fragment must be namespace qualified with one of the
> following prefixes".  This is accomplished in the report by way of an
> "inconsistency section" published at the end of the report:  if the
> section doesn't exist, there are no business rule
> inconsistencies.  Thus, the manager of a staff of XSLT stylesheet
> writers could express and enforce organizational business rules on
> the writing of XSLT stylesheets and refuse to accept a staff member's
> stylesheet as complete until the inconsistency report is empty.
>
> I did this for myself to ensure I would have no inconsistencies in my
> own stuff (reduces some of the early bugs from typos), but I'm
> learning from managers with whom I speak about this that this may,
> indeed, address a big problem they have enforcing the documentation
> of XSLT stylesheets in their shops.
>
> Two big browser hassles:
>
> (1) Internet Explorer deigns ".xsl" files not to be hyperlinked, thus
> all of the generated hyperlinks cannot be browsed after dragging the
> ".xsl" file in and seeing the printed report.
>
> (2) Firefox does not implement any node-set extension, so it just
> plain doesn't work.
>
> I get around both by using saxon with the "-a" option and producing
> an HTML file that can then be browsed by either.
>
> Also, a browsing harness, or test harness, can be used to get around
> (1) ... what I do is create a 10-line XSL stylesheet that imports the
> stylesheet I want documented, but I name this short stylesheet
> ".xml", and when I drag that into Internet Explorer, lo and behold,
> the hyperlinks happen to work.
>
> I've finally cleaned up my internal stuff to create a downloadable
> working example of this technique, and, guess what:  to read the
> documentation you have to drag the stylesheet into a browser or run
> it through an XSLT processor.
>
> I've named it XSLStyle and the code is available for free unfettered
> use with a flavour of the BSD license asking you to keep my copyright
> and not use the XSLStyle name to represent any other set of stylesheets.
>
> It is just a method for encapsulating documentation using any
> vocabulary, and the stylesheet processes the stripped out vocabulary
> using imported stylesheets.  It is "plug and play" with any
> vocabulary, and the downloaded package is documented using DocBook
> and includes the DocBook HTML stylesheets.  If you have your own
> installation of the DocBook stylesheets, then just modify a single
> import statement to point to it, then you can delete the
> subdirectory.  To support a different vocabulary, only change the
> template rules in that same single module and everything works.
>
> These stylesheets are, themselves, examples of stylesheets
> rigourously using namespace-qualified top-level construct names and
> modes.  I think that is the "magic" bit: by using namespace-qualified
> modes and template rules I can safely import DocBook, IC-MSP, or
> probably most other documentation vocabularies without ever risking
> an importation collision, as none of my constructs are in the
> null-URI namespace or unnamed mode.
>
> I've made this available through my web site linked below.  From the
> home page there are links on the right hand page.  Go to the "Free
> resources" link, to the "XSLT Resources" section to the "XSLStyle"
> subsection.  I won't publish the direct link in this post as I don't
> want the direct location archived in case it has to change.
>
> I look forward to any comments and I hope that people find this
> useful.  I plan to beef up the documentation based on feedback I receive.
>
> . . . . . . . . . Ken
>
> p.s. if anyone at Microsoft is reading this, please have your IE team
> review the decision to inhibit XSLT-transformed HTML hyperlinks when
> the file extension is other than ".xml" ... I would think that any
> file with any extension that happens to be XML on the inside,
> transformed with XSLT into HTML, should have the resulting HTML
> hyperlinks functional in the browser.  It was a real surprise that
> this wasn't the case.
>
> cc: XSL List, Yahoo XSL-FO, XML-Dev
>
> --
> World-wide on-site corporate, govt. & user group XML/XSL training.
> G. Ken Holman                 mailto:gkholman@xxxxxxxxxxxxxxxxxxxx
> Crane Softwrights Ltd.          http://www.CraneSoftwrights.com/s/
> Box 266, Kars, Ontario CANADA K0A-2E0    +1(613)489-0999 (F:-0995)
> Male Cancer Awareness Aug'05  http://www.CraneSoftwrights.com/s/bc
> Legal business disclaimers:  http://www.CraneSoftwrights.com/legal

---