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
|
xs3p - Version 1.0
==================
Index
-----
-Description
-Generating the documentation
-Viewing the documentation
-Configuring the stylesheet
Description
-----------
xs3p is a schema documentation generator. It is an XSLT stylesheet
that will output an XHTML document from an XSD schema. Aside from
using as much W3C acronyms as possible, the tool makes schemas more
readable by providing a view of schema components' constraints as a
sample XML instance, links that allow the user to jump to the
documentation of schema components that are referenced, and a whole
host of neat features. However, most important of all, it makes your
schemas look 'pretty in pink'.
Generating the documentation
----------------------------
To generate the documentation, you need a command-line XSLT tool that
supports the W3C XSLT 1.0 recommendation. (NOTE: xs3p does not work
with <?xml-stylesheet ?> processing instruction because the <A> links
in the generated XHTML document will not be correct.)
Here are a few examples of XSLT tools:
1. MSXML 4.0 (Windows only)
---------------------------
You can download MSXML 4.0 SP1 at:
http://msdn.microsoft.com/downloads/default.asp?
url=/downloads/sample.asp?url=/msdn-
files/027/001/766/msdncompositedoc.xml
(If the URL is incorrect, go to http://msdn.microsoft.com, and search
for the keywords, "msxml 4.0".)
Microsoft's web page gives you instructions of how to install the
MSXML 4.0 library. You'll also need to download Msxsl which is a
wrapper to access the library from the command-line. You can download
it at:
http://msdn.microsoft.com/downloads/default.asp?
URL=/downloads/sample.asp?url=/MSDN-
FILES/027/001/485/msdncompositedoc.xml
(Again, if the URL is incorrect, go to http://msdn.microsoft.com, and
search for the keyword, "msxsl".)
Click on the "Download the executable file" link. Save the msxsl.exe
file in a directory specified in the PATH environment variable. In
most cases, you can dump the file in c:\winnt (or c:\windows
depending on your OS) directory since it's already in the PATH
variable.
Type: msxsl -? to learn how to use the tool. The basic usage is:
msxsl [source] [stylesheet] -o [result] {[param-name]=[param-value]...}
2. Xalan (Java-based)
---------------------
You can download Xalan from Apache at:
http://xml.apache.org/xalan-j/getstarted.html
The web page gives you instructions of how to install Xalan. You can
find out how to use Xalan's command-line tool at:
http://xml.apache.org/xalan-j/commandline.html
The basic usage is:
java org.apache.xalan.xslt.Process -IN [source] -XSL [stylesheet]
-OUT [result] {-PARAM [param-name] [param-value]...}
3. Saxon (Java-based)
---------------------
You can download Saxon from Sourceforge at:
http://sourceforge.net/projects/saxon
If you download the saxon package, it comes with instructions of how
to install and use the Java jar files.
If you download the instant saxon package, it comes with a .exe file,
and all you have to do is put the file in a directory in the PATH
environment variable. It also comes with instant.html file, which
documents how to use it. The basic usage is:
saxon -o [result] [source] [stylesheet] {[param-name]=[param-value]...}
Viewing the documentation
-------------------------
To view the documentation, you need a browser that supports the W3C
XHTML 1.0 and CSS 2 recommendations, e.g.
-Internet Explorer 5.5 and above
-Netscape 6 and above
-Opera 5.0 and above
-Mozilla 1.0
Configuring the stylesheet
--------------------------
The xs3p stylesheet can be customised through its global parameters,
which are listed below.
title :-
You can specify your own title for the document, rather than
using the default one.
sortByComponent :-
If this parameter is set to "true", the schema components are
presented sorted by type and name. Otherwise, they are presented in
the order that they appear in the schema. By default, this parameter
is set to "true."
useJavaScript :-
The generated XHTML document uses JavaScript to hide some
details like the underlying schema component XML representation,
which can be made to appear with a button press. Since some people
have ideological objections to JavaScript, this feature can be turned
off. If this parameter is set to "true", JavaScript will be used in
the generated documentation. Otherwise, it won't. By default, this
parameter is set to "true."
printAllSuperTypes :-
The type hierarchy of a global type definition is displayed in
its section. If this parameter is set to "true", all super-types of
the current type are shown in the type hierarchy. Otherwise, only the
immediate parent type is displayed. By default, this parameter is set
to "true."
printAllSubTypes :-
This parameter has a similar concept as printAllSuperTypes. If
it is set to "true", all sub-types of the current type are shown in
the type hierarchy. Otherwise, only the direct sub-types are
displayed. By default, this parameter is set to "true."
printLegend :-
If this parameter is set to "true", the Legend section is
included. Otherwise, it isn't. By default, this parameter is set to
"true."
printGlossary :-
If this parameter is set to "true", the Glossary section is
included. Otherwise, it isn't. By default, this parameter is set to
"true."
printNSPrefixes :-
If this parameter is set to "true", namespace information is
provided when displaying sample instances and references. This is
done by providing a prefix in front of tags and references, which
when clicked, will take the user to the declared namespace. The
prefix matches the prefix in the namespace declaration in the schema.
If not set to "true", namespace prefixes are not displayed. By
default, this parameter is set to "true."
searchIncludedSchemas :-
If this parameter is set to "true", xs3p will search for
components in "included" schemas when creating links and generating
the XML Instance Representation table.
When this parameter is set to "true", the "linksFile" parameter
must also be set, which is described below. Otherwise, an error will
be raised.
The XSLT processor will also raise an error if it can't find the
schemas specified in the "schemaLocation" attribute of "include"
elements. XSLT implementations seem to resolve relative addresses
relative to the XSLT script, rather than the source file. This is a
common cause of error since in schemas, the "schemaLocation"
attribute is specified relative to the current schema. It is probably
best to write a script (e.g. Ant build file, DOS batch file, or Unix
shell script), which copies the xs3p stylesheet to the directory
containing the set of schemas and execute the XSLT script based on
the local copy.
The final thing to note is that this search is recursive, so
schemas "included" in the current schema's "included" schemas will
also be searched. This is another common source of error, since
schemas may be searched that might not have been thought about.
There are some batch files in the examples/ directory to show
how to use this feature. If you have 'msxsl', run "test_msxsl.bat"
file. If you use 'xalanj', run "test_xalanj.bat" file. Otherwise,
edit the files for your specific XSLT processor.
searchImportedSchemas :-
If this parameter is set to "true", xs3p will search for
components in "imported" schemas when creating links and generating
the XML Instance Representation table. The above discussion for the
"searchIncludedSchemas" parameter also applies to this parameter.
Also, when this parameter is set to "true", the "linksFile" parameter
must also be set.
linksFile :-
Specifies the file which maps from file locations of
"included" and "imported" schemas to the file locations of their
xs3p-generated documentation. This file must be provided if either
"searchIncludedSchemas" or "searchImportedSchemas" is set to true.
If relative addresses are used to specify the location of
external xs3p-generated documentation, they must be relative to
documentation file currently generated. NOTE: The external
documentation files does not need to exist at the time of generating
the documentation for the current schema.
The mapping is specified in XML. The dtd and schema for this
mapping syntax are "links.dtd" and "links.xsd" respectively.
A sample links file, "links.xml", is provided in the examples/
directory.
NOTE: The "xmlns" namespace attribute with the correct
namespace must be provided in the mapping file for the xs3p
stylesheet to work.
COPYRIGHT AND LICENCE
Copyright (C) 2001, 2002 DSTC Pty Ltd.
|
