[gtk+] Document the gtkbuilder xml file better

From: Matthias Clasen <matthiasc src gnome org>
To: commits-list gnome org
Cc:
Subject: [gtk+] Document the gtkbuilder xml file better
Date: Tue, 31 Jan 2012 01:33:54 +0000 (UTC)
commit 4497ac6b584cf94912e96db319f881bcc3df3107
Author: Matthias Clasen <mclasen redhat com>
Date:   Mon Jan 30 20:32:22 2012 -0500

    Document the gtkbuilder xml file better
    
    Replace the (invalid) DTD in the GtkBuilder docs by a
    RELAX NG schema. Also install the schema in /usr/share/gtk-3.0,
    so it can be used to validate GtkBuilder ui files.

 gtk/Makefile.am    |    6 +
 gtk/gtkbuilder.c   |   39 ++------
 gtk/gtkbuilder.rnc |   86 +++++++++++++++
 gtk/gtkbuilder.rng |  305 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 405 insertions(+), 31 deletions(-)
---
diff --git a/gtk/Makefile.am b/gtk/Makefile.am
index 6d5f926..55758a1 100644
--- a/gtk/Makefile.am
+++ b/gtk/Makefile.am
@@ -947,6 +947,12 @@ EXTRA_DIST += $(gtk_private_h_sources) $(gtk_extra_sources)
 EXTRA_DIST += $(gtk_built_sources)
 EXTRA_DIST += $(STOCK_ICONS)
 
+
+pkgdatadir=$(datadir)/gtk-$(GTK_API_VERSION)
+pkgdata_DATA = gtkbuilder.rng
+
+EXTRA_DIST += gtkbuilder.rnc gtkbuilder.rng
+
 DND_CURSORS = \
 	cursor_dnd_ask.png				\
 	cursor_dnd_copy.png				\
diff --git a/gtk/gtkbuilder.c b/gtk/gtkbuilder.c
index f4904fa..1f9d6e4 100644
--- a/gtk/gtkbuilder.c
+++ b/gtk/gtkbuilder.c
@@ -56,41 +56,18 @@
  * <title>GtkBuilder UI Definitions</title>
  * <para>
  * GtkBuilder parses textual descriptions of user interfaces which are specified
- * in an XML format which can be roughly described by the DTD below. We refer to
- * these descriptions as <firstterm>GtkBuilder UI definitions</firstterm> or
- * just <firstterm>UI definitions</firstterm> if the context is clear. Do not
+ * in an XML format which can be roughly described by the RELAX NG schema below.
+ * We refer to these descriptions as <firstterm>GtkBuilder UI definitions</firstterm>
+ * or just <firstterm>UI definitions</firstterm> if the context is clear. Do not
  * confuse GtkBuilder UI Definitions with
  * <link linkend="XML-UI">GtkUIManager UI Definitions</link>, which are more
  * limited in scope.
  * </para>
- * <programlisting><![CDATA[
- * <!ELEMENT interface (requires|object)* >
- * <!ELEMENT object    (property|signal|child|ANY)* >
- * <!ELEMENT property  PCDATA >
- * <!ELEMENT signal    EMPTY >
- * <!ELEMENT requires  EMPTY >
- * <!ELEMENT child     (object|ANY*) >
- *
- * <!ATTLIST interface  domain         	    #IMPLIED >
- * <!ATTLIST object     id             	    #REQUIRED
- *                      class          	    #REQUIRED
- *                      type-func      	    #IMPLIED
- *                      constructor    	    #IMPLIED >
- * <!ATTLIST requires   lib             	    #REQUIRED
- *                      version          	    #REQUIRED >
- * <!ATTLIST property   name           	    #REQUIRED
- *                      translatable   	    #IMPLIED
- *                      comments               #IMPLIED
- *                      context                #IMPLIED >
- * <!ATTLIST signal     name           	    #REQUIRED
- *                      handler        	    #REQUIRED
- *                      after          	    #IMPLIED
- *                      swapped        	    #IMPLIED
- *                      object         	    #IMPLIED
- *                      last_modification_time #IMPLIED >
- * <!ATTLIST child      type           	    #IMPLIED
- *                      internal-child 	    #IMPLIED >
- * ]]></programlisting>
+ * <programlisting>
+ * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gtk/gtkbuilder.rnc">
+ *   <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
+ * </xi:include>
+ * </programlisting>
  * <para>
  * The toplevel element is &lt;interface&gt;. It optionally takes a "domain"
  * attribute, which will make the builder look for translated strings using
diff --git a/gtk/gtkbuilder.rnc b/gtk/gtkbuilder.rnc
new file mode 100644
index 0000000..a2b4032
--- /dev/null
+++ b/gtk/gtkbuilder.rnc
@@ -0,0 +1,86 @@
+start = element interface {
+  attribute domain { text } ?,
+  ( requires | object | menu ) *
+}
+
+requires = element requires {
+  attribute lib { text },
+  attribute version { text }
+}
+
+object = element object {
+  attribute id { xsd:ID },
+  attribute class { text },
+  attribute type-func { text } ?,
+  attribute constructor { text } ?,
+  (property | signal | child | ANY) *
+}
+
+property = element property {
+  attribute name { text },
+  attribute translatable { "yes" | "no" } ?,
+  attribute comments { text } ?,
+  attribute context { text } ?,
+  text ?
+}
+
+signal = element signal {
+  attribute name { text },
+  attribute handler { text },
+  attribute after { text } ?,
+  attribute swapped { text } ?,
+  attribute object { text } ?,
+  attribute last_modification_time { text } ?,
+  empty
+}
+
+child = element child {
+  attribute type { text } ?,
+  attribute internal-child { text } ?,
+  (object | ANY)*
+}
+
+menu = element menu {
+  attribute id { xsd:ID },
+  attribute domain { text } ?,
+  (item | submenu | section) *
+}
+
+item = element item {
+  attribute id { xsd:ID } ?,
+  (attribute_ | link) *
+}
+
+attribute_ = element attribute {
+  attribute name { text },
+  attribute type { text } ?,
+  attribute translatable { "yes" | "no" } ?,
+  attribute context { text } ?,
+  attribute comments { text } ?,
+  text ?
+}
+
+link = element link {
+  attribute id { xsd:ID } ?,
+  attribute name { text },
+  item *
+}
+
+submenu = element submenu {
+  attribute id { xsd:ID } ?,
+  (attribute_ | item | submenu | section) *
+}
+
+section = element section {
+  attribute id { xsd:ID } ?,
+  (attribute_ | item | submenu | section) *
+}
+
+ANY = element * - (interface | requires | object | property | signal | child | menu | item | attribute | link | submenu | section) {
+  attribute * { text } *,
+  (ALL * & text ?)
+}
+ALL = element * {
+  attribute * { text } *,
+  (ALL * & text ?)
+}
diff --git a/gtk/gtkbuilder.rng b/gtk/gtkbuilder.rng
new file mode 100644
index 0000000..e36d051
--- /dev/null
+++ b/gtk/gtkbuilder.rng
@@ -0,0 +1,305 @@
+<?xml version="1.0"?>
+<grammar xmlns="http://relaxng.org/ns/structure/1.0"; ns="">
+  <start>
+    <element name="interface">
+      <optional>
+        <attribute name="domain">
+          <text/>
+        </attribute>
+      </optional>
+      <zeroOrMore>
+        <choice>
+          <ref name="requires"/>
+          <ref name="object"/>
+          <ref name="menu"/>
+        </choice>
+      </zeroOrMore>
+    </element>
+  </start>
+  <define name="requires">
+    <element name="requires">
+      <attribute name="lib">
+        <text/>
+      </attribute>
+      <attribute name="version">
+        <text/>
+      </attribute>
+    </element>
+  </define>
+  <define name="object">
+    <element name="object">
+      <attribute name="id">
+        <data type="ID" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"/>
+      </attribute>
+      <attribute name="class">
+        <text/>
+      </attribute>
+      <optional>
+        <attribute name="type-func">
+          <text/>
+        </attribute>
+      </optional>
+      <optional>
+        <attribute name="constructor">
+          <text/>
+        </attribute>
+      </optional>
+      <zeroOrMore>
+        <choice>
+          <ref name="property"/>
+          <ref name="signal"/>
+          <ref name="child"/>
+          <ref name="ANY"/>
+        </choice>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="property">
+    <element name="property">
+      <attribute name="name">
+        <text/>
+      </attribute>
+      <optional>
+        <attribute name="translatable">
+          <choice>
+            <value>yes</value>
+            <value>no</value>
+          </choice>
+        </attribute>
+      </optional>
+      <optional>
+        <attribute name="comments">
+          <text/>
+        </attribute>
+      </optional>
+      <optional>
+        <attribute name="context">
+          <text/>
+        </attribute>
+      </optional>
+      <optional>
+        <text/>
+      </optional>
+    </element>
+  </define>
+  <define name="signal">
+    <element name="signal">
+      <attribute name="name">
+        <text/>
+      </attribute>
+      <attribute name="handler">
+        <text/>
+      </attribute>
+      <optional>
+        <attribute name="after">
+          <text/>
+        </attribute>
+      </optional>
+      <optional>
+        <attribute name="swapped">
+          <text/>
+        </attribute>
+      </optional>
+      <optional>
+        <attribute name="object">
+          <text/>
+        </attribute>
+      </optional>
+      <optional>
+        <attribute name="last_modification_time">
+          <text/>
+        </attribute>
+      </optional>
+      <empty/>
+    </element>
+  </define>
+  <define name="child">
+    <element name="child">
+      <optional>
+        <attribute name="type">
+          <text/>
+        </attribute>
+      </optional>
+      <optional>
+        <attribute name="internal-child">
+          <text/>
+        </attribute>
+      </optional>
+      <zeroOrMore>
+        <choice>
+          <ref name="object"/>
+          <ref name="ANY"/>
+        </choice>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="menu">
+    <element name="menu">
+      <attribute name="id">
+        <data type="ID" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"/>
+      </attribute>
+      <optional>
+        <attribute name="domain">
+          <text/>
+        </attribute>
+      </optional>
+      <zeroOrMore>
+        <choice>
+          <ref name="item"/>
+          <ref name="submenu"/>
+          <ref name="section"/>
+        </choice>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="item">
+    <element name="item">
+      <optional>
+        <attribute name="id">
+          <data type="ID" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"/>
+        </attribute>
+      </optional>
+      <zeroOrMore>
+        <choice>
+          <ref name="attribute_"/>
+          <ref name="link"/>
+        </choice>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="attribute_">
+    <element name="attribute">
+      <attribute name="name">
+        <text/>
+      </attribute>
+      <optional>
+        <attribute name="type">
+          <text/>
+        </attribute>
+      </optional>
+      <optional>
+        <attribute name="translatable">
+          <choice>
+            <value>yes</value>
+            <value>no</value>
+          </choice>
+        </attribute>
+      </optional>
+      <optional>
+        <attribute name="context">
+          <text/>
+        </attribute>
+      </optional>
+      <optional>
+        <attribute name="comments">
+          <text/>
+        </attribute>
+      </optional>
+      <optional>
+        <text/>
+      </optional>
+    </element>
+  </define>
+  <define name="link">
+    <element name="link">
+      <optional>
+        <attribute name="id">
+          <data type="ID" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"/>
+        </attribute>
+      </optional>
+      <attribute name="name">
+        <text/>
+      </attribute>
+      <zeroOrMore>
+        <ref name="item"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="submenu">
+    <element name="submenu">
+      <optional>
+        <attribute name="id">
+          <data type="ID" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"/>
+        </attribute>
+      </optional>
+      <zeroOrMore>
+        <choice>
+          <ref name="attribute_"/>
+          <ref name="item"/>
+          <ref name="submenu"/>
+          <ref name="section"/>
+        </choice>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="section">
+    <element name="section">
+      <optional>
+        <attribute name="id">
+          <data type="ID" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"/>
+        </attribute>
+      </optional>
+      <zeroOrMore>
+        <choice>
+          <ref name="attribute_"/>
+          <ref name="item"/>
+          <ref name="submenu"/>
+          <ref name="section"/>
+        </choice>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="ANY">
+    <element>
+      <anyName>
+        <except>
+          <name>interface</name>
+          <name>requires</name>
+          <name>object</name>
+          <name>property</name>
+          <name>signal</name>
+          <name>child</name>
+          <name>menu</name>
+          <name>item</name>
+          <name>attribute</name>
+          <name>link</name>
+          <name>submenu</name>
+          <name>section</name>
+        </except>
+      </anyName>
+      <zeroOrMore>
+        <attribute>
+          <anyName/>
+          <text/>
+        </attribute>
+      </zeroOrMore>
+      <interleave>
+        <zeroOrMore>
+          <ref name="ALL"/>
+        </zeroOrMore>
+        <optional>
+          <text/>
+        </optional>
+      </interleave>
+    </element>
+  </define>
+  <define name="ALL">
+    <element>
+      <anyName/>
+      <zeroOrMore>
+        <attribute>
+          <anyName/>
+          <text/>
+        </attribute>
+      </zeroOrMore>
+      <interleave>
+        <zeroOrMore>
+          <ref name="ALL"/>
+        </zeroOrMore>
+        <optional>
+          <text/>
+        </optional>
+      </interleave>
+    </element>
+  </define>
+</grammar>
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]