1 line
9.1 KiB
Plaintext
1 line
9.1 KiB
Plaintext
$Id: sddRefDebugDoc.txt,v 1.1 2004/09/07 14:28:38 JacobAsiedu Exp efghttpd $
|
|
|
|
SDD key/ref Debugger : a keyref debugging aid.
|
|
|
|
I. INTRODUCTION
|
|
=============================
|
|
The SDD Schema comprises many elements which use the key/keyref mechanism for making things in the Description section and elsewhere in SDD instance documents refer to things in the Terminology section (and elsewhere). Usually, these keys and keyrefs are meaningless integers, and it is desirable to be able to tell from the keyref where the keyed object actually is, and to see some snippet of text describing it. Often, there already is such a snippet associated with the keyed object, but finding it by hand can be tiresome. This tool uses heuristics to select one of the possible several bits of text on the keyed object and insert it in the optional "debugref" attribute on the object which is the reference.
|
|
|
|
The tool is based on XSLT and can be used either as a standalone Java program we provide that includes the Apache xalan XSLT engine, or with an XSLT engine of your own choosing, such as the one included in XSLT Spy. The latter is convenient if you use Spy as an instance document editor.
|
|
|
|
II. Installation
|
|
|
|
To install the tool, choose a directory of your choice, and unzip the installation package sddRefDebug.zip into that directory (unix/linux users: untar sddRefDebug.tar).
|
|
|
|
|
|
|
|
II)Standalone java tool
|
|
============================
|
|
|
|
i. Installation
|
|
|
|
You must have a Java Runtime Environment (JRE) installed.
|
|
We have not tested this tool with anything lower than JRE 1.4.
|
|
If you have no Java support installed, you can fetch it from http://java.com
|
|
|
|
|
|
To check the version of your JRE, open a command window and at the command prompt type:
|
|
java -version
|
|
|
|
If the version of the JRE is at least 1.4, follow the installation instructions in Section II above.
|
|
|
|
ii. Usage
|
|
|
|
Open a command window and cd to the installation directory
|
|
ii.a)WINDOWS users:
|
|
At the command prompt enter: sddRefDebug.bat
|
|
ii.b)Linux/UNIX users:
|
|
If your system is capable of running X-Windows
|
|
i) At the command prompt enter: sddRefDebug.sh
|
|
ii)At the command prompt enter: sddRefDebugNoWindows.sh XML_FILE_NAME OUT_PUT_FILE_NAME [quiet | verbose]
|
|
replace XML_FILE_NAME with the full path to your sdd instance document
|
|
replace OUPUT_FILE_NAME with the name you would like to call the transformed document
|
|
verbose - Produces a more verbose output.
|
|
The default is quiet.
|
|
|
|
The tool is generally self explanatory, but from the main menu of the window that appears,
|
|
you can select Help->Contents to learn more about using it
|
|
|
|
iii. Caveat about instance documents
|
|
|
|
The Apache xalan XML parser that is used by the java tool---and indeed the Namespace
|
|
specification itself--requires that all namespaces must be declared in the instance
|
|
document explicitly. A fatal error is reported if an element is bound to an undeclared
|
|
namespace.
|
|
See http://www.w3.org/TR/REC-xml-names/#ns-using. Some tools, including some versions
|
|
of XML Spy are lax about this requirement.
|
|
|
|
|
|
|
|
III. Use with XML Spy
|
|
|
|
This section explains the use of sddRefDebug with XML Spy. Please pay particular attention
|
|
to the "Caveats" and "Known Defects" sections.
|
|
|
|
i. Normal deployment and use:
|
|
|
|
0. From the distribution directory, copy source/sddRefDebug.xsl or source/sddRefDebugVerbose.xsl
|
|
into a working directory. These files distinguish a normal from a verbose version of the tool
|
|
|
|
1. Open Spy against your instance document. From the XSL menu,
|
|
select XSL Transformation (or use the F10 function key). The first time you do this, a dialogue
|
|
will invite you to specify where the XSLT is to be found. You should point to wherever you
|
|
copied the debugging xsl files in step 0. Click OK. This should create a new file which should
|
|
be the same as your original instance document except for the text added to the debugref
|
|
attributes on elements that have keyref attributes.
|
|
|
|
ii. Caveats using sddRefDebug with XML Spy
|
|
|
|
We have only tested these instructions and the tool with Spy 2004 Enterprise Edition, Release 3.
|
|
|
|
You might care to configure Spy for sane behavior by bringing up the Options/XSL dialogue with
|
|
Tools->Options->XSL and change the "Default file extension of output file" to xml, and
|
|
select "Reuse output window". These settings are appropriate to this debugging use,
|
|
though the defaults may be appropriate if you are trying to generate html from an instance
|
|
document with some XSLT you have written. This only needs to be done once.
|
|
|
|
iv. Known Defects using sddRefDebug with XML Spy
|
|
|
|
1. The XSLT engine in Spy 2004 Enterprise Edition R3 Spy's XSLT has a bug that causes inappropriate
|
|
input to be put into an output document in the case where the input document's xsi:schemaLocation
|
|
has a newline separating the two required parts of the attribute value. This is not fatal to this
|
|
application, but you will be happier if you don't have it. Thus, instead of
|
|
xsi:schemaLocation="http://www.tdwg.org/2003/SDD
|
|
SDD.xsd"
|
|
you should have
|
|
xsi:schemaLocation="http://www.tdwg.org/2003/SDD SDD.xsd"
|
|
Should you prefer the newline, the symptom and workaround are described at the end of this document in
|
|
the section on known defects, under "Spy xsi:schemaLocation newline bug"
|
|
|
|
Symptom: the constructed document will have the entity refrence 
 between the two parts of the
|
|
xsi:schemaLocation attribute. This will cause validation to fail immediately
|
|
(because Spy attempts to validate newly created documents if they have a schema named in them).
|
|
Cure: You must replace 
 with any whitespace, including a newline, unless you don't care about
|
|
validation of the debugging document (which is a dangerous position...)
|
|
|
|
Workaround: avoid newline inside the xsi:schemaLocation in your instance documents.
|
|
|
|
2. XSLT output documents fail to validate
|
|
|
|
Cause: By default Spy builds output of XSLT in a temp directory, but the schema you are using is
|
|
somewhere else. If you have relative xsi:schemaLocation values, this will never be right.
|
|
|
|
Workarounds:
|
|
1. Use absolute xsi:schemaLocation attribute values. This is unappealing because they are almost always
|
|
wrong as soon as you move your instance document to another computer, or serve it on the web.
|
|
|
|
2. If the xsi:schemaLocation is relative, save the XSLT output, here usually the debugging instance document,
|
|
in a directory where that relative location can actually be found, then revalidate the document.
|
|
|
|
3. Use Spy Projects. They allow you to control all this pain.
|
|
|
|
|
|
IV) General technical details and customization
|
|
|
|
The tool consists of two xslt files, sddRefDebug.xsl and sddRefDebugVerbose.xsl which can be found in the
|
|
"source" subdirectory of the installation directory.
|
|
|
|
Earlier sections document how to use sddRefDebug with our standalone Java invocation of Apache xalan and
|
|
with XML Spy, but all that is really required is to execute one of these XSLT files against the SDD instance
|
|
document you wish to transform. Any XSLT engine should suffice. The result should be a file with the "debugref"
|
|
attributes completed in a reasonbly helpful way. For other engines, we welcome commentary added to the SDD
|
|
Wiki under the tools topic at http://efgblade.cs.umb.edu/twiki/bin/view/SDD/ToolsForUseWithSDD
|
|
|
|
1)Differences between sddRefDebug.xsl and sddRefDebugVerbose.xsl:
|
|
|
|
sddRefDebugVerbose.xsl inserts XPATH expressions together with the text on the keyed object into the optional
|
|
"debugRef" attribute mentioned in the preceding paragraph. sddRefDebug.xsl inserts only the text on the keyed
|
|
object into the optional "debugRef" attribute.
|
|
|
|
2)Customization
|
|
|
|
The customizations described here should work with any XSLT engines. In particular, they should work equally
|
|
well with our standalone Java program (which invokes Apache xalan against them) and with XML Spy used as
|
|
described earlier. We have not tested customization extensively and do not support it.
|
|
|
|
By default the tool documents every debugref. If you want to suppress this for entire classes of keys,
|
|
simply comment out the line of sddRefDebug.xsl/sddRefDebugVerbose.xsl that corresponds to the class of
|
|
keyrefs you wish to suppress. For example, a Character in a Description is only identified by an integer
|
|
referring to something in the Terminology section. If you wish to debug only Characters, comment every
|
|
<xsl:key> element out of sddRefDebug.xsl and sddRefDebugVerbose.xsl except the line
|
|
|
|
<xsl:key name="Character"
|
|
match="sdd:Terminology/sdd:Characters/sdd:Character" use="@id" />
|
|
|
|
If you find it convenient to rearrange the order of the <xsl:key> elements you can do so without harm.
|
|
|
|
The tool uses heuristics documented at a web location given in the commentary of sddRefDebug.xsl and
|
|
sddRefDebugVerbose.xsl, but these heuristics might not suit you. However, each keyed object contains
|
|
not only a key attribute, but also an attribute named debugText. You can put anything you wish there.
|
|
If there is something there, sddRefDebug.xsl and sddRefDebugVerbose.xsl will ignore the heuristics
|
|
and use that text instead.
|
|
|
|
3) Tests:
|
|
Test files can be found in the 'test' directory of the main application folder.
|
|
|
|
|
|
Jacob Asiedu
|
|
Robert A. Morris
|
|
|
|
Electronic Field Guide Project
|
|
http://www.cs.umb.edu/efg
|
|
|
|
|