began for maemo

[xscreensaver] / xscreensaver / hacks / config / xss.xsd

<?xml version="1.0" encoding="UTF-8"?>
<!-- xscreensaver, Copyright (c) 2001-2005 Jamie Zawinski <jwz@jwz.org> -->
<!--
 Permission to use, copy, modify, distribute, and sell this software and its
 documentation for any purpose is hereby granted without fee, provided that
 the above copyright notice appear in all copies and that both that
 copyright notice and this permission notice appear in supporting
 documentation.  No representations are made about the suitability of this
 software for any purpose.  It is provided "as is" without express or
 implied warranty.
-->
<!--  XScreenSaver schema version 0.5

This schema validates the format of the XScreenSaver configuration files.

The notices shown above, appear at the top of the source of 'demo-Gtk-conf.c'.
Since this schema (attempts to) describe the format of the existing
XScreenSaver configuration files, it seems appropriate to reproduce them here.
If it is not appropriate, please ignore/remove them rather than sue me.

To check a savername.xml, reference this XSD from the file and validate it at
  http://www.w3.org/2001/03/webdata/xsv

** Background
Andrew Thompson defined a DTD based on his understanding of the
XScreenSaver configuration files after examining the files..
xscreensaver-4.22
  |- hacks
  |    |- config
  |         README
  |         *.xml
  |- driver
       demo-Gtk-conf.c

Paul Dennis generated an XSD file (xscreensaver.xsd) from the DTD.
This is a stricter version of that XSD, with more comments and
documentation by Andrew Thompson.

Note that Andrew does not program in c, and has not had the
opportunity to see XScreenSaver in action (he runs Windows),
so some of the details of the schema may be incorrect.  It aims
to be cautious, and thus might be more strict than is actually
required.

** .XSD started as version 0.1
- generated from the DTD.
- checked parameter types
  - mostly as xs:string, except for..
  - ID's - checked as xs:ID.
- provided grouping parse logic, but specified elements
    with maxOccurs 'unbounded'

** Tightened parsing in 0.2
- The only field still defined as xs:string is the _description.
- A substitutionArgumentType has been introduced to lock the form of
    the arg to '-lettersandnumbers %'
- An argumentType has been introduced to ensure other
    arg/arg-set/arg-unset attributes begin with '-' and
    are followed by at least one letter or number.
- Float and integer numeric values (low/high/default) are checked as xs:decimal
- Remaining attributes were tightened from xs:string to xs:token.

** Tightened parsing in 0.3
  * Note that no maximums at all are stated in the XScreenSaver README!
- maxOccurs lowered from 'unbounded' to
  - screensaver: '200' components/groups
  - screensaver: '40' commands/fullcommands
  - select: '100' options
  - hgroup: '6' components/groups per row
  - vgroup: '40' components/groups per column
- maxLength of _description set to '2000' chars.

** Changes in version 0.4 - Strict
    After testing against the configuration files of the XScreenSaver
    hacks, the following changes were made..
- Added (+ _ / $) to allowable characters for substitutionArgumentType
    & argumentType, but tightened baseType to xs:token
- maxOccurs changed to
  - screensaver: '200' -> '30' components/groups
      (xmountains.xml has 24)
  - screensaver: '40' -> '10' commands/fullcommands
  - select: '100' -> '200' options
      (to account for polyhedra.xml, which has 152 options!)
  - hgroup: '6' -> '4' components/groups per row
      (glplanet.xml has 4)
  - vgroup: '40' -> '10' components/groups per column
      (bsod.xml has 9)
- maxLength of _description changed from '2000' to '3000' chars,
    (covers the largest _description, 'jigglypuff.xml', at 852 chars,
    'magicrainbow.xml', at 2837 chars.)
- introduced idType to facilitate maintenance between the
    strict and loose schemas.

** Changes in version 0.4 - Loose
- made _label of number element optional (when using sliders, some
    developers put what would normally appear in the _label, as a
    prefix to _low-label instead)
- widens the idType base type from xs:ID to xs:token.  Since the ID is
    unimplemented and will most likely remain so, it makes little
    sense to ensure they are unique & valid ID's.

** Changes in 0.5 - Strict
- Minor typos. to 0.4 docs fixed.
- Since both the XScreenSaver code and Saverbeans SettingsDialog
seem tolerant to the _label of the number element missing, it is
marked as 'optional' now, even in the strict version.

** Limits: This version
- specifies the 'arg-set'/'arg-unset' of 'boolean' as optional, whereas it
    requires exactly one of either 'arg-set' or 'arg-unset'.
- cannot properly distinguish between the 'slider' and 'spinbutton' types
    of the 'number' element.  As a result of that, '_low-label'/'_high-label'
    are specified as not required, whereas they are actually undefined for
    'spinbutton' and required for 'slider'.
- has no checks to ensure that 'default' values of ranges in the
    number element fall between 'low' & 'high' values.
- Selects can have no more than one option missing an arg-set attribute. 
- Arguments must be unique, but this schema does not check that.
- _label is effectively optional for the slider type of the number element,
    since this info can be preprended to the _low-label, but no checks are 
    done to ensure that the spinbutton type has the _label.

** Undocumented.
'undocumented' means that the element/feature was not mentioned in the
official documentation of the format available in the -
xscreensaver-4.22/hacks/config/README.
-->
<xs:schema
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  elementFormDefault="qualified">

  <!-- The root element of any XScreenSaver configuration file. -->
  <xs:element name="screensaver">
    <xs:complexType>
      <xs:sequence>
        <!-- Every XScreenSaver hack has exactly one of either
        command or fullcommand, but my understanding is that
        demo-Gtk-conf.c chains them together.
        This specifies a maximum numner of commands. -->
        <xs:choice minOccurs="0" maxOccurs="10">
          <xs:element ref="command"/>
          <xs:element ref="fullcommand"/>
        </xs:choice>
        <!-- A maximum number of components/groups is specified.  -->
        <xs:choice minOccurs="0" maxOccurs="30">
          <xs:element ref="boolean"/>
          <xs:element ref="number"/>
          <xs:element ref="select"/>
          <xs:element ref="string"/>
          <xs:element ref="file"/>
          <xs:element ref="hgroup"/>
          <xs:element ref="vgroup"/>
        </xs:choice>
        <xs:element ref="_description"/>
      </xs:sequence>
      <xs:attribute name="name" type="xs:token" use="required"/>
      <xs:attribute name="_label" type="xs:token" use="required"/>
    </xs:complexType>
  </xs:element>

  <!-- Added to the command line when invoked.  -->
  <xs:element name="command">
    <xs:complexType>
      <xs:attribute name="arg" type="argumentType"/>
    </xs:complexType>
  </xs:element>

  <!-- Unimplemented in SaverBeans as of API 0.2.
  Used only by cosmos.xml.  Undocumented. -->
  <xs:element name="fullcommand">
    <xs:complexType>
      <xs:attribute name="arg" type="argumentType"/>
    </xs:complexType>
  </xs:element>

  <!-- Checkbox -->
  <xs:element name="boolean">
    <xs:complexType>
      <xs:attribute name="id" type="idType"/>
      <xs:attribute name="_label" type="xs:token" use="required"/>
      <!-- Exactly one of either arg-set or arg-unset is required -->
      <xs:attribute name="arg-set" type="argumentType"/>
      <xs:attribute name="arg-unset" type="argumentType"/>
    </xs:complexType>
  </xs:element>

  <!-- Slider and Spinbutton -->
  <xs:element name="number">
    <xs:complexType>
      <xs:attribute name="id" type="idType"/>
      <xs:attribute name="type" use="required">
        <xs:simpleType>
          <xs:restriction base="xs:NMTOKEN">
            <xs:enumeration value="slider"/>
            <xs:enumeration value="spinbutton"/>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
      <!-- Listed as 'required' in the documentation, though XScreenSaver is
      tolerant to it being left out.  A number of hacks deliberately exclude it
      for formatting purposes, and put the _label as prefix to _low-label -->
      <xs:attribute name="_label" type="xs:token" />
      <!-- _low/_high-label not defined for type spinbutton,
      but required for slider -->
      <xs:attribute name="_low-label" type="xs:token"/>
      <xs:attribute name="_high-label" type="xs:token"/>
      <xs:attribute name="arg" type="substitutionArgumentType" use="required"/>
      <xs:attribute name="low" type="xs:decimal" use="required"/>
      <xs:attribute name="high" type="xs:decimal" use="required"/>
      <!-- Must logically fall between low and high, but not checked. -->
      <xs:attribute name="default" type="xs:decimal" use="required"/>
      <xs:attribute name="convert">
        <xs:simpleType>
          <xs:restriction base="xs:NMTOKEN">
            <xs:enumeration value="invert"/>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
    </xs:complexType>
  </xs:element>

  <!-- Drop-down list -->
  <xs:element name="select">
    <xs:complexType>
      <xs:sequence>
        <!-- A maximum number of options is specified, as a longer
        drop down becomes kludgy and difficult to use.  -->
        <xs:element ref="option" maxOccurs="200"/>
      </xs:sequence>
      <xs:attribute name="id" type="idType"/>
    </xs:complexType>
  </xs:element>

  <!-- List item -->
  <xs:element name="option">
    <xs:complexType>
      <xs:attribute name="id" type="idType"/>
      <xs:attribute name="_label" type="xs:token" use="required"/>
      <xs:attribute name="arg-set" type="argumentType"/>
    </xs:complexType>
  </xs:element>

  <!-- String or textual input -->
  <xs:element name="string">
    <xs:complexType>
      <xs:attribute name="id" type="idType"/>
      <xs:attribute name="_label" type="xs:token" use="required"/>
      <xs:attribute name="arg" type="substitutionArgumentType" use="required"/>
    </xs:complexType>
  </xs:element>

  <!-- File browser. -->
  <xs:element name="file">
    <xs:complexType>
      <xs:attribute name="id" type="idType"/>
      <xs:attribute name="_label" type="xs:token" use="required"/>
      <xs:attribute name="arg" type="substitutionArgumentType" use="required"/>
    </xs:complexType>
  </xs:element>

    <!-- Free Text.  The description of the Screen Saver. -->
    <xs:element name="_description">
      <!-- The _description must contain text only, with no HTML formatting.

      Character entities are also valid, which suggests that..
        http://www.w3.org/TR/REC-html40/sgml/entities.html
      ..are valid entities, though this, ..
        http://www.w3.org/TR/1998/REC-html40-19980424/sgml/entities.html#h-24.4.1
      ..may represent a safer sub-set.

      The main entities you might require (none of which are allowed
      in textual content in an XML file) are..
       &lt; (= <)
       &gt; (= >)
       &amp; (= &)

      XScreenSaver itself will probably* turn any URL enclosed in
      &lt; / &gt; into a clickable link.

      Conversion to an URL is unimplemented in SaverBeans as of API 0.2.

      It might be possible to implement this in SaverBeans with the help of
      BrowserLauncher, though that would require about 20Kb (AFAIR) of extra
      classes in the core API distributable.

      * This is based solely on the use of the delimiters in many of the
      XScreenSaver hacks, but has not been investigated in any depth.
      -->
      <xs:simpleType>
        <xs:restriction base="xs:string">
          <xs:maxLength value="3000"/>
        </xs:restriction>
      </xs:simpleType>
    </xs:element>

    <!-- Horizontal grouping element, a row of components or groups.
    Unimplemented in SaverBeans as of API 0.2,
    components inside groups do not appear.  -->
    <xs:element name="hgroup">
      <xs:complexType>
        <!-- A maximum number of components/groups per row is specified. -->
        <xs:choice minOccurs="0" maxOccurs="4">
          <xs:element ref="boolean"/>
          <xs:element ref="number"/>
          <xs:element ref="select"/>
          <xs:element ref="string"/>
          <xs:element ref="file"/>
          <xs:element ref="vgroup"/>
        </xs:choice>
      </xs:complexType>
    </xs:element>

    <!-- Vertical grouping element, a column of components or groups.
    Since the components are normally arranged in a column,
    this is only of use within an hgroup.
    Unimplemented in SaverBeans as of API 0.2,
    components inside groups do not appear.  -->
    <xs:element name="vgroup">
      <xs:complexType>
        <!-- A maximum number of components/groups per column is specified. -->
        <xs:choice minOccurs="0" maxOccurs="10">
          <xs:element ref="boolean"/>
          <xs:element ref="number"/>
          <xs:element ref="select"/>
          <xs:element ref="string"/>
          <xs:element ref="file"/>
          <xs:element ref="hgroup"/>
        </xs:choice>
      </xs:complexType>
    </xs:element>

    <!-- Checks that the command arguments (non substitution arg, as
    well as arg-set/arg-unset) are of a logical (and restricted) form.
    This determines that the type must start with '-', and contain at
    least one letter, number or the other characters shown in the RegEx.
    It is stricter than the XScreenSaver documentation suggests. -->
    <xs:simpleType name="argumentType">
      <xs:restriction base="xs:token">
        <xs:minLength value="2"/>
        <xs:pattern value="-([a-zA-Z0-9 .,;:+_$#%?/\\\-])*"/>
      </xs:restriction>
    </xs:simpleType>

    <!-- Checks that the command arguments that use substitution are of
    a logical (and quite restricted) form.  This determines that the
    type must start with '-', contain at least one letter, number
    or the other characters shown in the RegEx.
    It is stricter than the XScreenSaver documentation suggests. -->
    <xs:simpleType name="substitutionArgumentType">
      <xs:restriction base="xs:token">
        <xs:minLength value="4"/>
        <xs:pattern value="-([a-zA-Z0-9.,;:+_$#%?/\\\-])* %"/>
      </xs:restriction>
    </xs:simpleType>

    <!-- idType is used to validate the ID's
    Many ID's do not parse as type xs:ID, so this type was created to
    allow easy maintenance between the strict and loose versions of the schema.
    The base type should be
     - xs:ID in the strict schema, and
     - xs:token in the loose schema.
    Note that the base type of xs:ID overrides the minLength value of '0'
    -->
    <xs:simpleType name="idType">
      <!-- strict -->
      <xs:restriction base="xs:ID">
      <!-- loose -->
      <!--
      <xs:restriction base="xs:token">
      -->
        <xs:minLength value="0"/>
      </xs:restriction>
    </xs:simpleType>

</xs:schema>