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(_at_)cranesoftwrights(_dot_)com> 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(_at_)CraneSoftwrights(_dot_)com
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
--~------------------------------------------------------------------
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>
--~--
--~------------------------------------------------------------------
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>
--~--