Commit 4497ac6b authored by Matthias Clasen's avatar Matthias Clasen

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.
parent 585a6652
......@@ -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 \
......
......@@ -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
......
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 ?)
}
<?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>
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment