1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- xscreensaver, Copyright (c) 2001-2005 Jamie Zawinski <jwz@jwz.org> -->
4 Permission to use, copy, modify, distribute, and sell this software and its
5 documentation for any purpose is hereby granted without fee, provided that
6 the above copyright notice appear in all copies and that both that
7 copyright notice and this permission notice appear in supporting
8 documentation. No representations are made about the suitability of this
9 software for any purpose. It is provided "as is" without express or
12 <!-- XScreenSaver schema version 0.5
14 This schema validates the format of the XScreenSaver configuration files.
16 The notices shown above, appear at the top of the source of 'demo-Gtk-conf.c'.
17 Since this schema (attempts to) describe the format of the existing
18 XScreenSaver configuration files, it seems appropriate to reproduce them here.
19 If it is not appropriate, please ignore/remove them rather than sue me.
21 To check a savername.xml, reference this XSD from the file and validate it at
22 http://www.w3.org/2001/03/webdata/xsv
25 Andrew Thompson defined a DTD based on his understanding of the
26 XScreenSaver configuration files after examining the files..
35 Paul Dennis generated an XSD file (xscreensaver.xsd) from the DTD.
36 This is a stricter version of that XSD, with more comments and
37 documentation by Andrew Thompson.
39 Note that Andrew does not program in c, and has not had the
40 opportunity to see XScreenSaver in action (he runs Windows),
41 so some of the details of the schema may be incorrect. It aims
42 to be cautious, and thus might be more strict than is actually
45 ** .XSD started as version 0.1
46 - generated from the DTD.
47 - checked parameter types
48 - mostly as xs:string, except for..
49 - ID's - checked as xs:ID.
50 - provided grouping parse logic, but specified elements
51 with maxOccurs 'unbounded'
53 ** Tightened parsing in 0.2
54 - The only field still defined as xs:string is the _description.
55 - A substitutionArgumentType has been introduced to lock the form of
56 the arg to '-lettersandnumbers %'
57 - An argumentType has been introduced to ensure other
58 arg/arg-set/arg-unset attributes begin with '-' and
59 are followed by at least one letter or number.
60 - Float and integer numeric values (low/high/default) are checked as xs:decimal
61 - Remaining attributes were tightened from xs:string to xs:token.
63 ** Tightened parsing in 0.3
64 * Note that no maximums at all are stated in the XScreenSaver README!
65 - maxOccurs lowered from 'unbounded' to
66 - screensaver: '200' components/groups
67 - screensaver: '40' commands/fullcommands
68 - select: '100' options
69 - hgroup: '6' components/groups per row
70 - vgroup: '40' components/groups per column
71 - maxLength of _description set to '2000' chars.
73 ** Changes in version 0.4 - Strict
74 After testing against the configuration files of the XScreenSaver
75 hacks, the following changes were made..
76 - Added (+ _ / $) to allowable characters for substitutionArgumentType
77 & argumentType, but tightened baseType to xs:token
78 - maxOccurs changed to
79 - screensaver: '200' -> '30' components/groups
80 (xmountains.xml has 24)
81 - screensaver: '40' -> '10' commands/fullcommands
82 - select: '100' -> '200' options
83 (to account for polyhedra.xml, which has 152 options!)
84 - hgroup: '6' -> '4' components/groups per row
86 - vgroup: '40' -> '10' components/groups per column
88 - maxLength of _description changed from '2000' to '3000' chars,
89 (covers the largest _description, 'jigglypuff.xml', at 852 chars,
90 'magicrainbow.xml', at 2837 chars.)
91 - introduced idType to facilitate maintenance between the
92 strict and loose schemas.
94 ** Changes in version 0.4 - Loose
95 - made _label of number element optional (when using sliders, some
96 developers put what would normally appear in the _label, as a
97 prefix to _low-label instead)
98 - widens the idType base type from xs:ID to xs:token. Since the ID is
99 unimplemented and will most likely remain so, it makes little
100 sense to ensure they are unique & valid ID's.
102 ** Changes in 0.5 - Strict
103 - Minor typos. to 0.4 docs fixed.
104 - Since both the XScreenSaver code and Saverbeans SettingsDialog
105 seem tolerant to the _label of the number element missing, it is
106 marked as 'optional' now, even in the strict version.
108 ** Limits: This version
109 - specifies the 'arg-set'/'arg-unset' of 'boolean' as optional, whereas it
110 requires exactly one of either 'arg-set' or 'arg-unset'.
111 - cannot properly distinguish between the 'slider' and 'spinbutton' types
112 of the 'number' element. As a result of that, '_low-label'/'_high-label'
113 are specified as not required, whereas they are actually undefined for
114 'spinbutton' and required for 'slider'.
115 - has no checks to ensure that 'default' values of ranges in the
116 number element fall between 'low' & 'high' values.
117 - Selects can have no more than one option missing an arg-set attribute.
118 - Arguments must be unique, but this schema does not check that.
119 - _label is effectively optional for the slider type of the number element,
120 since this info can be preprended to the _low-label, but no checks are
121 done to ensure that the spinbutton type has the _label.
124 'undocumented' means that the element/feature was not mentioned in the
125 official documentation of the format available in the -
126 xscreensaver-4.22/hacks/config/README.
129 xmlns:xs="http://www.w3.org/2001/XMLSchema"
130 elementFormDefault="qualified">
132 <!-- The root element of any XScreenSaver configuration file. -->
133 <xs:element name="screensaver">
136 <!-- Every XScreenSaver hack has exactly one of either
137 command or fullcommand, but my understanding is that
138 demo-Gtk-conf.c chains them together.
139 This specifies a maximum numner of commands. -->
140 <xs:choice minOccurs="0" maxOccurs="10">
141 <xs:element ref="command"/>
142 <xs:element ref="fullcommand"/>
144 <!-- A maximum number of components/groups is specified. -->
145 <xs:choice minOccurs="0" maxOccurs="30">
146 <xs:element ref="boolean"/>
147 <xs:element ref="number"/>
148 <xs:element ref="select"/>
149 <xs:element ref="string"/>
150 <xs:element ref="file"/>
151 <xs:element ref="hgroup"/>
152 <xs:element ref="vgroup"/>
154 <xs:element ref="_description"/>
156 <xs:attribute name="name" type="xs:token" use="required"/>
157 <xs:attribute name="_label" type="xs:token" use="required"/>
161 <!-- Added to the command line when invoked. -->
162 <xs:element name="command">
164 <xs:attribute name="arg" type="argumentType"/>
168 <!-- Unimplemented in SaverBeans as of API 0.2.
169 Used only by cosmos.xml. Undocumented. -->
170 <xs:element name="fullcommand">
172 <xs:attribute name="arg" type="argumentType"/>
177 <xs:element name="boolean">
179 <xs:attribute name="id" type="idType"/>
180 <xs:attribute name="_label" type="xs:token" use="required"/>
181 <!-- Exactly one of either arg-set or arg-unset is required -->
182 <xs:attribute name="arg-set" type="argumentType"/>
183 <xs:attribute name="arg-unset" type="argumentType"/>
187 <!-- Slider and Spinbutton -->
188 <xs:element name="number">
190 <xs:attribute name="id" type="idType"/>
191 <xs:attribute name="type" use="required">
193 <xs:restriction base="xs:NMTOKEN">
194 <xs:enumeration value="slider"/>
195 <xs:enumeration value="spinbutton"/>
199 <!-- Listed as 'required' in the documentation, though XScreenSaver is
200 tolerant to it being left out. A number of hacks deliberately exclude it
201 for formatting purposes, and put the _label as prefix to _low-label -->
202 <xs:attribute name="_label" type="xs:token" />
203 <!-- _low/_high-label not defined for type spinbutton,
204 but required for slider -->
205 <xs:attribute name="_low-label" type="xs:token"/>
206 <xs:attribute name="_high-label" type="xs:token"/>
207 <xs:attribute name="arg" type="substitutionArgumentType" use="required"/>
208 <xs:attribute name="low" type="xs:decimal" use="required"/>
209 <xs:attribute name="high" type="xs:decimal" use="required"/>
210 <!-- Must logically fall between low and high, but not checked. -->
211 <xs:attribute name="default" type="xs:decimal" use="required"/>
212 <xs:attribute name="convert">
214 <xs:restriction base="xs:NMTOKEN">
215 <xs:enumeration value="invert"/>
222 <!-- Drop-down list -->
223 <xs:element name="select">
226 <!-- A maximum number of options is specified, as a longer
227 drop down becomes kludgy and difficult to use. -->
228 <xs:element ref="option" maxOccurs="200"/>
230 <xs:attribute name="id" type="idType"/>
235 <xs:element name="option">
237 <xs:attribute name="id" type="idType"/>
238 <xs:attribute name="_label" type="xs:token" use="required"/>
239 <xs:attribute name="arg-set" type="argumentType"/>
243 <!-- String or textual input -->
244 <xs:element name="string">
246 <xs:attribute name="id" type="idType"/>
247 <xs:attribute name="_label" type="xs:token" use="required"/>
248 <xs:attribute name="arg" type="substitutionArgumentType" use="required"/>
252 <!-- File browser. -->
253 <xs:element name="file">
255 <xs:attribute name="id" type="idType"/>
256 <xs:attribute name="_label" type="xs:token" use="required"/>
257 <xs:attribute name="arg" type="substitutionArgumentType" use="required"/>
261 <!-- Free Text. The description of the Screen Saver. -->
262 <xs:element name="_description">
263 <!-- The _description must contain text only, with no HTML formatting.
265 Character entities are also valid, which suggests that..
266 http://www.w3.org/TR/REC-html40/sgml/entities.html
267 ..are valid entities, though this, ..
268 http://www.w3.org/TR/1998/REC-html40-19980424/sgml/entities.html#h-24.4.1
269 ..may represent a safer sub-set.
271 The main entities you might require (none of which are allowed
272 in textual content in an XML file) are..
277 XScreenSaver itself will probably* turn any URL enclosed in
278 < / > into a clickable link.
280 Conversion to an URL is unimplemented in SaverBeans as of API 0.2.
282 It might be possible to implement this in SaverBeans with the help of
283 BrowserLauncher, though that would require about 20Kb (AFAIR) of extra
284 classes in the core API distributable.
286 * This is based solely on the use of the delimiters in many of the
287 XScreenSaver hacks, but has not been investigated in any depth.
290 <xs:restriction base="xs:string">
291 <xs:maxLength value="3000"/>
296 <!-- Horizontal grouping element, a row of components or groups.
297 Unimplemented in SaverBeans as of API 0.2,
298 components inside groups do not appear. -->
299 <xs:element name="hgroup">
301 <!-- A maximum number of components/groups per row is specified. -->
302 <xs:choice minOccurs="0" maxOccurs="4">
303 <xs:element ref="boolean"/>
304 <xs:element ref="number"/>
305 <xs:element ref="select"/>
306 <xs:element ref="string"/>
307 <xs:element ref="file"/>
308 <xs:element ref="vgroup"/>
313 <!-- Vertical grouping element, a column of components or groups.
314 Since the components are normally arranged in a column,
315 this is only of use within an hgroup.
316 Unimplemented in SaverBeans as of API 0.2,
317 components inside groups do not appear. -->
318 <xs:element name="vgroup">
320 <!-- A maximum number of components/groups per column is specified. -->
321 <xs:choice minOccurs="0" maxOccurs="10">
322 <xs:element ref="boolean"/>
323 <xs:element ref="number"/>
324 <xs:element ref="select"/>
325 <xs:element ref="string"/>
326 <xs:element ref="file"/>
327 <xs:element ref="hgroup"/>
332 <!-- Checks that the command arguments (non substitution arg, as
333 well as arg-set/arg-unset) are of a logical (and restricted) form.
334 This determines that the type must start with '-', and contain at
335 least one letter, number or the other characters shown in the RegEx.
336 It is stricter than the XScreenSaver documentation suggests. -->
337 <xs:simpleType name="argumentType">
338 <xs:restriction base="xs:token">
339 <xs:minLength value="2"/>
340 <xs:pattern value="-([a-zA-Z0-9 .,;:+_$#%?/\\\-])*"/>
344 <!-- Checks that the command arguments that use substitution are of
345 a logical (and quite restricted) form. This determines that the
346 type must start with '-', contain at least one letter, number
347 or the other characters shown in the RegEx.
348 It is stricter than the XScreenSaver documentation suggests. -->
349 <xs:simpleType name="substitutionArgumentType">
350 <xs:restriction base="xs:token">
351 <xs:minLength value="4"/>
352 <xs:pattern value="-([a-zA-Z0-9.,;:+_$#%?/\\\-])* %"/>
356 <!-- idType is used to validate the ID's
357 Many ID's do not parse as type xs:ID, so this type was created to
358 allow easy maintenance between the strict and loose versions of the schema.
359 The base type should be
360 - xs:ID in the strict schema, and
361 - xs:token in the loose schema.
362 Note that the base type of xs:ID overrides the minLength value of '0'
364 <xs:simpleType name="idType">
366 <xs:restriction base="xs:ID">
369 <xs:restriction base="xs:token">
371 <xs:minLength value="0"/>