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
|