-
Notifications
You must be signed in to change notification settings - Fork 21
/
readme.html
227 lines (197 loc) · 6.93 KB
/
readme.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/>
<title>Schmit: SCHema In Transformation</title>
<style>
pre.console {
background-color: black;
color: white;
font-weight: bold;
padding: 0.5em;
margin-left: 2em;
}
pre.xml {
background-color: rgb(230,230,255);
color: navy;
font-weight: bold;
padding: 0.5em;
margin-left: 2em;
}
span.customization {
color: red;
}
</style>
</head><body>
<div style="text-align:center; font-size: 2em;">
Schmit: SCHema In Transformation
</div>
<div align=right style="font-size:smaller">
By <a href="mailto:kohsuke.kawaguchi@sun.com">Kohsuke Kawaguchi</a><br>
</div>
<h2>Table of Contents</h2>
<ol>
<li><a href="#intro">Introduction</a>
<li><a href="#start">Getting Started</a>
<li><a href="#xsd">XML Schema</a>
<li><a href="#reference">Reference</a>
<li><a href="#contact">Contact</a>
<li><a href="#former-project-proposal">Former-project-proposal</a>
</ol>
<a name="intro"/>
<h2>Introduction</h2>
<p>
Schmit is an <a href="http://www.w3.org/TR/xslt">XSLT</a> <a href="http://xml.apache.org/xalan-j/extensions.html">extension</a> that allows you to access schema annotation information from within the stylesheet.
This functionality can be used to write more generic stylesheet that isn't tied to any particular XML vocabulary.
The current release works for <a href="http://xml.apache.org/xalan-j/index.html">Apache Xalan</a>.
</p>
<a name="start"/>
<h2>Getting Started</h2>
</p>
To use Schmit, you first prepare a schema that validates the input of the transformation. For example, if you are converting a DocBook to XHTML, you need a schema for DocBook. Schmit supports <a href="http://relaxng.org">RELAX NG</a> and <a href="http://www.w3.org/TR/xmlschema-0">W3C XML Schema</a>.
</p><p>
Assume you have the following schema:
</p>
<pre class=xml><xmp>
<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0"
xmlns:a="test">
<start>
<element name="root">
<element name="child" a:note="1st">
<empty/>
</element>
<element name="child" a:note="2nd">
<empty/>
</element>
</element>
</start>
</grammar>
</grammar>
</xmp></pre>
<p>
Note that this schema contains attributes from namespace "test". Schmit treats all the non-RELAX NG namespaces in a grammar as "annotations". For XML Schema, elements and attributes inside <xs:annotation> are considered as "annotations".
</p>
<p>
Inside your stylesheet, you first declare Schmit as an XSLT extension:
</p>
<pre class=xml><xmp>
<?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
xmlns:sc="xalan://com.sun.msv.schmit.XalanExtension"
extension-element-prefixes="sc">
</xmp></pre>
<p>
As usual, you can use any prefix instead of "sc". But in this document, we assume that the prefix "sc" is used for the extension declaration.
</p><p>
Next, you need to tell the processor to apply the above schema to the input.
This will be done by using the <code>sc:useSchema</code> extension element.
This can be done at the very beginning of the stylesheet:
</p>
<pre class=xml><xmp>
<xsl:template match="/">
<sc:useSchema href="myschema.rng" />
...
</xsl:template>
</xmp></pre>
<p>
The <code>href</code> attribute points to the location of the schema. When this instruction is executed, the schema is loaded.
</p><p>
Once you load a schema, you can use another extension function <code>sc:annotation</code> to obtain the annotation.
</p>
<pre class=xml><xmp>
<xsl:template match="/">
<result>
<sc:useSchema href="myschema.rng" />
<xsl:for-each select="root/child">
<note>
<xsl:value-of select="sc:annotation(.)/@a:note" />
</note>
</xsl:for-each>
</result>
</xsl:template>
</xmp></pre>
<p>
The <code>sc:annotation</code> function takes a node set, and returns a node set that contains all the annotation elemetns/attributes attached to it. In the above example, we are retriving the value of the <code>a:note</code> attribute attached to each <code>child</code> element.
</p><p>
If an input looks like:
</p>
<pre class=xml><xmp>
<?xml version="1.0"?>
<root>
<child/>
<child/>
</root>
</xmp></pre>
<p>
Then the result will look like:
</p>
<pre class=xml><xmp>
<?xml version="1.0"?>
<result>
<note>1st</note>
<note>2nd</note>
</result>
</xmp></pre>
<p>
The use of <code>sc:annotation</code> is not limited to <code>xsl:value-of</code>; it can be used anywhere where you can write XPath functions. For example, you can write a template matching rule like this:
</p>
<pre class=xml><xmp>
<xsl:template match="*[sc:annotation(.)/@a:visible]">
</xmp></pre>
<p>
which will match any element whose definition have <code>a:visible</code> attribute, or you can write:
</p>
<pre class=xml><xmp>
<xsl:copy-of select="sc:annotation(.)/a:htmldoc/*" />
</xmp></pre>
<p>
which copies HTML documentation of the current element (assuming that you've written one inside schema) into the current location.
</p>
<a name="xsd" />
<h2>XML Schema</h2>
<p>
When you choose W3C XML Schemas as your schema language, you need to use the <code>sc:annotation</code> like this:
</p>
<pre class=xml><xmp>
<xsl:copy-of select="sc:annotation(.)/xs:appinfo/foo:myAnnotation" />
</xmp></pre>
<p>
In other words, you can assume that this method returns <code>xs:annotation</code> element itself --- therefore you need to be prepared to see elements like <code>xs:appinfo</code> or <code>xs:documentation</code> before you get to your own annotation.
</p>
<a name="reference" />
<h2>Reference</h2>
</p>
Schmit has one extension element and one extension function. This section defines the syntax of those extensions.
<p>
<h3><code>useSchema</code> extension element</h3>
<pre class=xml><xmp>
<sc:useSchema href="[attribute value template]" />
</xmp></pre>
<p>
Loads a schema from the specified location and annotate the current input document (the document that includes the context node) with it.
</p><p>
The href attribute takes an attribute value template, meaning that you can write things like this:
</p>
<pre class=xml><xmp>
<sc:useSchema href="foo.rng" />
<sc:useSchema href="${myVariable}" />
</xmp></pre>
<h3><code>annotation</code> extension function</h3>
<pre class=xml><xmp>
sc:annotation()
sc:annotation([node-set])
</xmp></pre>
<p>
Looks up the annotation attached to the specified nodes, and returns them as a node set.
<code>sc:annotation()</code> is equivalent of <code>sc:annotation(.)</code>.
</p>
<a name="contact" />
<h2>Contact</h2>
<p>
If you have any comment or suggestion to this technology, please feel free to drop a note to <a href="mailto:kohsuke.kawaguchi@sun.com">Kohsuke Kawaguchi</a>.
</p>
<a name="former-project-proposal" />
<h2>Former Project Proposal</h2>
<p>
The former project proposal can be found <a href="former-project-proposal.txt">here</a>.
</p>
</body></html>