From: Dick Hamilton <rlhamilton@frii.com> Date: Tue, 4 Apr 2006 22:27:04 +0000 (+0000) Subject: Add Customization section. X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=a58eadcb1514254f43dde41ed34c98dc43190a36;p=docbook-dsssl Add Customization section. --- diff --git a/docbook/relaxng/docbook/howto/howto.xml b/docbook/relaxng/docbook/howto/howto.xml index da23aa76d..d4582ee33 100644 --- a/docbook/relaxng/docbook/howto/howto.xml +++ b/docbook/relaxng/docbook/howto/howto.xml @@ -17,9 +17,10 @@ <contrib>§convert4to5, proofreading</contrib></author> <author><personname>Dick Hamilton</personname> <email>rlhamilton@frii.com</email> - <contrib>§changes-removed, proofreading</contrib></author> + <contrib>§changes-removed, customization, proofreading</contrib></author> </authorgroup> +<pubdate>2006-04-04</pubdate> <pubdate>2006-03-01</pubdate> <pubdate>2005-12-28</pubdate> <pubdate>2005-10-27</pubdate> @@ -941,20 +942,682 @@ linkend="convert4to5"/>. </section> <section xml:id="customizations"> -<title>Customizing DocBook V5.0</title> + <title>Customizing DocBook V5.0</title> + <!-- + ** RNG schema organization + ** Removing attributes + ** Adding new attributes + ** Changing permitted content of attribute + ** Removing elements + ** Adding new elements + ** Customizing content models + ** Naming and versioning of DocBook customizations + --> + + <para> + It's much easier to customize DocBook V5.0 than it was to + customize earlier releases. This is partly because RELAX NG + provides better support for modifications than DTDs and partly + because the DocBook schema is designed to take full advantage + of the capabilities RELAX NG provides. + This section describes the organization of the RELAX NG schema for + DocBook, methods and examples for adding, removing, and modifying elements + and attributes, and conventions for naming and versioning + DocBook customizations. + It assumes some familiarity with RELAX NG. If you are unfamiliar + with RELAX NG, you can find a tutorial introduction in + <citation>RNCTUT</citation>. + </para> + <section xml:id="relaxngorg"> + <title>DocBook RELAX NG schema organization</title> + <para> + The DocBook RELAX NG schema is highly modular, using named + patterns extensively. Every element, attribute, attribute + list, and enumeration has its own named pattern. In addition, + there are named patterns for logical combinations of elements + and attributes. These named patterns provide <quote>hooks</quote> + into the schema that allow you to do a wide range of customization + by simply redefining one or more of the named patterns. + </para> + <para> + An important design characteristic of the schema is that + duplication is minimized. This is done through the use of + named patterns for common groupings that can be re-used. + For example, the <tag>imagedata</tag> and <tag>videodata</tag> + elements each have an <tag class="attribute">align</tag> attribute + that takes the same set of enumerated values. Rather than + repeating those values, a single pattern, + <varname>db.halign.enumeration</varname> is referenced by + the <varname>db.videodata.align.enumeration</varname> + and <varname>db.imagedata.align.enumeration</varname> patterns, + which are in turn referenced by the + <varname>db.videodata.align.attribute</varname> + and <varname>db.imagedata.align.attribute</varname> patterns. + While this may seem like overkill, it allows a customizer to modify + the allowed enumerations for these two attributes separately or together, + or to completely re-define the allowed content of either or both, + by redefining one or more of these named patterns. + </para> + <section xml:id="patternnames"><title>Pattern Names</title> + <para> + Because named patterns are used extensively, the RELAX NG schema uses + several naming conventions. These are: + <itemizedlist spacing="compact"> + <listitem> + <para> + Names have two or more parts, separated dots <quote>.</quote> + </para> + </listitem> + <listitem> + <para> + The first part of each name is the prefix <quote>db</quote> + </para> + </listitem> + <listitem> + <para> + Each element has a named pattern in the form + <varname>db.<replaceable>elementname</replaceable></varname>. + Elements that have different content models in different + contexts will also have patterns in the form + <varname>db.<replaceable>context.elementname</replaceable></varname>. For example, <varname>db.figure.info</varname> + defines the content model for the <tag>info</tag> element + when it appears as a child of the <tag>figure</tag> element. + <replaceable>Context</replaceable> may have several parts. + For example, <varname>db.cals.entrytbl.thead</varname>. + </para> + </listitem> + <listitem> + <para> + Most attributes have a named pattern in the form + <varname>db.<replaceable>attributename</replaceable>.attribute</varname>. + Attributes that have different content models in different + contexts will also have patterns in the form + <varname>db.<replaceable>context.attributename</replaceable>.attribute</varname>. + For example, + <varname>db.olink.localinfo.attribute</varname> defines the content + model of the <tag class="attribute">localinfo</tag> attribute when + it appears in <tag>olink</tag>. + There are a few attributes that do not have individual named + patterns. For example, the effectivity attributes are grouped + into <varname>db.effectivity.attributes</varname> and not identified + separately. + </para> + </listitem> + <listitem> + <para> + Each element has a named pattern for its attribute list in + the form + <varname>db.<replaceable>elementname</replaceable>.attlist</varname> + + that defines the list of attributes for that element. + Elements that have different attribute lists in different + contexts will also have patterns in the form + <varname>db.<replaceable>context.elementname</replaceable>.attlist</varname> + For example, <varname>db.html.table.attlist</varname> defines + the attribute list for the html <tag condition="nolink">table</tag> element and + <varname>db.cals.table.attlist</varname> defines the attribute + list for a cals <tag condition="nolink">table</tag> element. + </para> + </listitem> + <listitem> + <para> + Each attribute that has enumerated values has a + named pattern in the form + <varname>db.<replaceable>[context.]attributename</replaceable>.enumeration</varname>. + If the enumeration for a particular attribute depends on + context, optional context is provided. + For example, + <varname>db.verbatim.continuation.enumeration</varname> defines + the enumeration values for the + <tag class="attribute">continuation</tag> attribute that is used + in verbatim contexts like <tag>screen</tag>. + Unlike elements and attributes, there is not necessarily a + named pattern for enumerated attributes outside their context. + For example, there is no <varname>db.class.enumeration</varname> + because the <tag class="attribute">class</tag> attribute has + a broad and non-intersecting range of uses. + </para> + </listitem> + <listitem> + <para> + There are several different groupings of elements and attributes. + Here are the major ones: + <variablelist spacing="compact"> + <varlistentry> + <term>inlines</term> + <listitem> + <para> + Combinations of inline elements, for example, + <varname>db.error.inlines</varname>, which contains + <varname>db.errorcode</varname>, + <varname>db.errortext</varname>, etc. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>blocks</term> + <listitem> + <para> + Combinations of block elements, for example, + <varname>db.verbatim.blocks</varname>, which contains + <varname>db.programlisting</varname>, + <varname>db.screen</varname>, etc. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>attributes</term> + <listitem> + <para> + Combinations of attributes, for example, + <varname>db.effectivity.attributes</varname>, + which contains the attributes + <tag class="attribute">arch</tag>, + <tag class="attribute">condition</tag>, + <tag class="attribute">conformance</tag>, etc. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>components</term> + <listitem> + <para> + High level components of the schema, for example, + <varname>db.navigation.components</varname>, which contains + <varname>db.glossary</varname>, + <varname>db.bibliography</varname>, + <varname>db.index</varname>, and + <varname>db.toc</varname>, and is used inside the + content model for <tag>chapter</tag>, <tag>appendix</tag>, + and <tag>preface</tag>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>contentmodel</term> + <listitem> + <para> + Shared content models, for example, + <varname>db.admonition.contentmodel</varname>, which contains + the content model for <tag>tip</tag>, <tag>warning</tag>, + <tag>note</tag>, etc. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + There are a couple of other groupings designed to minimize + duplication, but these are the most important. + </para> + </listitem> + </itemizedlist> + </para> + </section> +</section> +<section xml:id="customconsiderations"> + <title>General customization considerations</title> + <para> + Creating a customized schema is similar to + creating a customization layer for XSL. The schema customization + layer is a new RELAX NG schema that defines your changes and + includes the standard docbook schema. You then validate using + the schema customization as your schema. + </para> + <para> + <xref linkend="ex-empty" xrefstyle="select: label"/> is an empty + RELAX NG customization that does nothing + except define the name spaces and include the standard DocBook schema. + The <tag class="attribute">href</tag> attribute of the + <tag condition="nolink">include</tag> element points to + the location of the standard DocBook V5.0 schema. + All of the examples are given in both RNG and RNC form. +<example xml:id="ex-empty"><title>Empty customization file</title> +<para>RNG</para> +<programlisting language="rng"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<grammar xmlns:db="http://docbook.org/ns/docbook" + ns="http://docbook.org/ns/docbook" + xmlns="http://relaxng.org/ns/structure/1.0"> + <include href="docbook.rng"/> + + <!-- redefinitions of named patterns --> + +</grammar>]]></programlisting> +<para>RNC</para> +<programlisting language="rnc"><![CDATA[namespace db = "http://docbook.org/ns/docbook" + +include "docbook.rnc" inherit = db +# redefinitions of named patterns]]></programlisting> +</example> + </para> +</section> + <section xml:id="cust-elements"> + <title>Elements</title> + <section xml:id="cust-add-elements"> + <title>Adding elements</title> + <para> + Adding an element typically takes two definitions. + The first defines the new element and + its content model, and the second adds the + new element into the schema. We'll show two examples. + </para> + <para> + <xref linkend="ex-add-element-1" xrefstyle="select: label"/> + adds a new element, + <tag condition="nolink">person</tag>, with the same + content model as <tag>author</tag>. The new element will be + allowed to appear wherever <tag>author</tag> can appear. + </para> + <para> + The <varname>db.author</varname> pattern is copied + and renamed <varname>dbx.person</varname>, defining + a new element called <tag condition="nolink">person</tag>. + Then, the <varname>db.author</varname> pattern is redefined + to be a choice of the current value or <varname>dbx.person</varname>. + The <tag class="attribute">combine</tag> attribute tells + RELAX NG to combine this pattern with the existing named + pattern. In this case, the value + of the <tag class="attribute">combine</tag> attribute is + <quote>choice</quote>, which tells the parser that either + the original pattern or this new pattern is a valid match. + </para> +<example xml:id="ex-add-element-1"><title>Adding a new element by duplicating an existing one</title> +<para>RNG</para> +<programlisting language="rng"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<grammar xmlns:db="http://docbook.org/ns/docbook" + ns="http://docbook.org/ns/docbook" + xmlns="http://relaxng.org/ns/structure/1.0"> + <include href="docbook.rng"/> + <!-- define the new element --> + <define name="dbx.person"> + <element name="person"> + <ref name="db.author.attlist"/> + <ref name="db.credit.contentmodel"/> + </element> + </define> + <!-- redefine the db.author pattern to allow db.person in + the same places as db.author --> + <define name="db.author" combine="choice"> + <ref name="dbx.person"/> + </define> +</grammar>]]></programlisting> +<para>RNC</para> +<programlisting language="rnc"><![CDATA[default namespace db = "http://docbook.org/ns/docbook" + +include "docbook.rnc" +# define the new element +dbx.person = + element person { db.author.attlist, db.credit.contentmodel } +# redefine the db.author pattern to allow db.person in +# the same places as db.author +db.author |= dbx.person]]></programlisting> +</example> + <para> + The preceding method works well when you'd like a new element + to be a clone or near-clone of an existing element. It gives + you complete control over the content model, but + only limited control over where the element is allowed. It + works well when you want to allow the element in the same places + as an existing element, and for this example that works + nicely, since <tag>author</tag> is allowed in four different + named patterns, each of which would have had to be redefined to + allow <tag condition="nolink">person</tag>. + But, if you can't find an existing element that is allowed in + exactly the places you need, this method doesn't work as well. + </para> + <para> + <xref linkend="ex-add-element-2" xrefstyle="select: label"/> + adds two new elements by combining them into + a higher level pattern. In this example, we'll add + two new inline elements for writing about assembly language, + <tag condition="nolink">register</tag> and + <tag condition="nolink">instruction</tag>. + We will allow them whereever programming inlines + or operating system inlines are allowed. + <xref linkend="ex-add-element-2" xrefstyle="select: label"/> + defines the two elements, creates a new named pattern + (<varname>dbx.asm.inlines</varname>) that contains them, and adds + that pattern to <varname>db.programming.inlines</varname> and + <varname>db.os.inlines</varname>. Since these two patterns + don't have any elements in common, the strategy used in + <xref linkend="ex-add-element-1" xrefstyle="select: label"/> + would require selecting two different elements to <quote>clone</quote>, + which would be messy. + </para> +<example xml:id="ex-add-element-2"><title>Adding new inline elements</title> +<para>RNG</para> +<programlisting language="rng"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<grammar xmlns:db="http://docbook.org/ns/docbook" + ns="http://docbook.org/ns/docbook" + xmlns="http://relaxng.org/ns/structure/1.0"> + <include href="docbook.rng"/> + <!-- define the new elements --> + <define name="dbx.register"> + <element name="register"> + <text/> + </element> + </define> + <define name="dbx.instruction"> + <element name="instruction"> + <text/> + </element> + </define> + <!-- create a new pattern that contains the new inlines --> + <define name="dbx.asm.inlines"> + <choice> + <ref name="dbx.register"/> + <ref name="dbx.instruction"/> + </choice> + </define> + <!-- add the new inlines to programming and os inlines --> + <define name="db.programming.inlines" combine="choice"> + <ref name="dbx.asm.inlines"/> + </define> + <define name="db.os.inlines" combine="choice"> + <ref name="dbx.asm.inlines"/> + </define> +</grammar>]]></programlisting> +<para>RNC</para> +<programlisting language="rnc"><![CDATA[default namespace db = "http://docbook.org/ns/docbook" + +include "docbook.rnc" +# define the new elements +dbx.register = element register { text } +dbx.instruction = element instruction { text } +# create a new pattern that contains the new inlines +dbx.asm.inlines = dbx.register | dbx.instruction +# add the new inlines to programming and os inlines +db.programming.inlines |= dbx.asm.inlines +db.os.inlines |= dbx.asm.inlines]]></programlisting> +</example> + </section> + <section xml:id="cust-delete-elements"> + <title>Deleting elements</title> + <para> + Deleting elements is straightforward, but takes some + care and planning. <xref linkend="ex-delete-element" + xrefstyle="select: label"/> deletes + the <tag>important</tag> admonition element by redefining + it with a content model of <varname>notAllowed</varname>. + Note that in this example, the redefinition is inside + the <tag condition="nolink">include</tag> element. + This is required for + redefinitions that completely replace an existing pattern. + </para> + <para> + Be careful; If you delete an element that is a required part + of another element's content model, you can make it + impossible to create a valid document. + For example, if you delete the <tag>title</tag> + element, you won't be able to validate a <tag>book</tag> + because a <tag>book</tag> requires a <tag>title</tag>. + </para> +<example xml:id="ex-delete-element"><title>Deleting an element</title> +<para>RNG</para> +<programlisting language="rng"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<grammar xmlns:db="http://docbook.org/ns/docbook" + ns="http://docbook.org/ns/docbook" + xmlns="http://relaxng.org/ns/structure/1.0"> + <include href="docbook.rng"> + <!-- redefine important element as notAllowed --> + <define name="db.important"> + <notAllowed/> + </define> + </include> +</grammar>]]></programlisting> +<para>RNC</para> +<programlisting language="rnc"><![CDATA[namespace db = "http://docbook.org/ns/docbook" + +include "docbook.rnc" inherit = db { + # redefine important element as notAllowed + db.important = notAllowed +}]]></programlisting> +</example> + </section> + <section xml:id="cust-modify-elements"> + <title>Customizing the content model of existing elements</title> + <para> + <xref linkend="ex-modify-element" xrefstyle="select: label"/> + expands the definition of <tag>author</tag> to include two + new elements, <tag condition="nolink">born</tag> and + <tag condition="nolink">died</tag>. + The <tag>author</tag> element allows two content models, + <varname>db.person.author.contentmodel</varname>, which + defines an author who is a person, and + <varname>db.org.author.contentmodel</varname>, which + defines an author that is an organization. We will modify + <varname>db.person.author.contentmodel</varname> so that + only authors who are persons can have the new elements. +<example xml:id="ex-modify-element"><title>Modifying the content model of an element</title> +<para>RNG</para> +<programlisting language="rng"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<grammar xmlns:db="http://docbook.org/ns/docbook" + ns="http://docbook.org/ns/docbook" + xmlns="http://relaxng.org/ns/structure/1.0"> + <include href="docbook.rng"/> + + <define name="db.person.author.contentmodel" combine="interleave"> + <interleave> + <optional> + <element name="born"> + <ref name="db.date.contentmodel"/> + </element> + </optional> + <optional> + <element name="died"> + <ref name="db.date.contentmodel"/> + </element> + </optional> + </interleave> + </define> +</grammar>]]></programlisting> +<para>RNC</para> +<programlisting language="rnc"><![CDATA[default namespace = "http://docbook.org/ns/docbook" +namespace db = "http://docbook.org/ns/docbook" + +include "docbook.rnc" + +db.person.author.contentmodel &= + element born { db.date.contentmodel }? + & element died { db.date.contentmodel }?]]></programlisting> +</example> + </para> + <para> + This modification will allow instances like this: +<programlisting language="rng"><![CDATA[<author> + <personname>Babe Ruth</personname> + <born>02/06/1895</born> + <died>08/16/1948</died> +</author>]]></programlisting> +but because we only modified the content model for authors +who are human, it won't allow an instance like this, which +uses <varname>db.org.author.contentmodel</varname>: +<programlisting language="rng"><![CDATA[<!-- INVALID --> +<author> + <orgname>Boston Red Sox</orgname> + <died>1919</died> + <born>2004</born> +</author>]]></programlisting> + </para> + </section> + </section> + <section xml:id="cust-attributes"> + <title>Attributes</title> + <section xml:id="cust-add-attributes"> + <title>Adding attributes</title> + <para> + The simplest way to add an attribute to a single element + is to add it to the attlist pattern for that element. + <xref linkend="ex-add-attr" xrefstyle="select: label"/> + adds the optional attributes <tag class="attribute">born</tag> + and <tag class="attribute">died</tag> to the attribute + list for <tag>author</tag>. The <varname>db.author.attlist</varname> + named pattern is redefined with the + <tag class="attribute">combine</tag> attribute set to + <quote>interleave</quote>, which interleaves the two new + optional attributes with the existing attributes on the list. + </para> +<example xml:id="ex-add-attr"><title>Adding attributes</title> +<para>RNG</para> +<programlisting language="rng"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<grammar xmlns:db="http://docbook.org/ns/docbook" + ns="http://docbook.org/ns/docbook" + xmlns="http://relaxng.org/ns/structure/1.0"> + <include href="docbook.rng"/> + + <define name="db.author.attlist" combine="interleave"> + <interleave> + <optional> + <attribute name="born"> + <ref name="db.date.contentmodel"/> + </attribute> + </optional> + <optional> + <attribute name="died"> + <ref name="db.date.contentmodel"/> + </attribute> + </optional> + </interleave> + </define> +</grammar>]]></programlisting> +<para>RNC</para> +<programlisting language="rnc"><![CDATA[namespace db = "http://docbook.org/ns/docbook" + +include "docbook.rnc" inherit = db -<para>TBD</para> +db.author.attlist &= + attribute born { db.date.contentmodel }? + & attribute died { db.date.contentmodel }?]]></programlisting> +</example> + <para> + Unlike + <xref linkend="ex-modify-element" xrefstyle="select: label"/>, + <xref linkend="ex-add-attr" xrefstyle="select: label"/> allows + the new attributes to appear on any <tag>author</tag> + element, not just those using the person content model. + </para> + <para> + <xref linkend="ex-add-attr-2" xrefstyle="select: label"/> shows + how you could limit the use of these attributes to authors who + are persons. In this example, the new attributes are interleaved + with the <varname>db.person.author.contentmodel</varname>. + The only difference between this example and + <xref linkend="ex-modify-element" xrefstyle="select: label"/> is + that the added patterns are identified as attributes rather than + elements. This shows some of the flexibility of RELAX NG, which + treats attributes and elements very consistently. +<example xml:id="ex-add-attr-2"><title>Adding attributes; alternate method</title> +<para>RNG</para> +<programlisting language="rng"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<grammar xmlns:db="http://docbook.org/ns/docbook" + ns="http://docbook.org/ns/docbook" + xmlns="http://relaxng.org/ns/structure/1.0"> + <include href="docbook.rng"/> + <!-- redefinitions of named patterns --> + <define name="db.person.author.contentmodel" combine="interleave"> + <interleave> + <optional> + <attribute name="born"> + <ref name="db.date.contentmodel"/> + </attribute> + </optional> + <optional> + <attribute name="died"> + <ref name="db.date.contentmodel"/> + </attribute> + </optional> + </interleave> + </define> +</grammar>]]></programlisting> +<para>RNC</para> +<programlisting language="rnc"><![CDATA[namespace db = "http://docbook.org/ns/docbook" + +include "docbook.rnc" inherit = db +# redefinitions of named patterns +db.person.author.contentmodel &= + attribute born { db.date.contentmodel }? + & attribute died { db.date.contentmodel }?]]></programlisting> +</example> +There is one difference in the treatment of attributes and elements +that is worth noting. By the XML 1.0 definition, the relative order +of attributes is not significant. Therefore, the +<tag condition="nolink">interleave</tag> block is not required for +attributes, though it does no harm. + </para> + </section> + <section xml:id="cust-delete-attributes"> + <title>Deleting attributes</title> + <para> + Deleting an attribute is similar to deleting an element, + except that you use the RELAX NG <varname>empty</varname> + pattern rather than <varname>notAllowed</varname>. + <xref linkend="ex-delete-attr" xrefstyle="select: label"/> + deletes the linking attributes, which are collected in the + <varname>db.common.linking.attributes</varname> pattern, + by defining that pattern as <varname>empty</varname>. + </para> +<example xml:id="ex-delete-attr"><title>Deleting an attribute</title> +<para>RNG</para> +<programlisting language="rng"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<grammar xmlns:db="http://docbook.org/ns/docbook" + ns="http://docbook.org/ns/docbook" + xmlns="http://relaxng.org/ns/structure/1.0"> + <include href="docbook.rng"> + <define name="db.common.linking.attributes"> + <empty/> + </define> + </include> +</grammar>]]></programlisting> +<para>RNC</para> +<programlisting language="rnc"><![CDATA[namespace db = "http://docbook.org/ns/docbook" -<!-- -** RNG schema organization -** Removing attributes -** Adding new attributes -** Changing permitted content of attribute -** Removing elements -** Adding new elements -** Customizing content models -** Naming and versioning of DocBook customizations ---> +include "docbook.rnc" inherit = db { + db.common.linking.attributes = empty +}]]></programlisting> +</example> + <para> + Generally, <varname>empty</varname> is used when deleting + attributes and <varname>notAllowed</varname> is used when + deleting elements. + </para> + </section> + <section xml:id="cust-modify-attributes"> + <title>Changing permitted content of attributes</title> + <para> + <xref linkend="ex-modify-attr" xrefstyle="select: label"/> + modifies <varname>db.spacing.enumeration</varname> to + add the additional value <quote>large</quote>. Note + that to remove a value from an enumeration, you need + to redefine the entire enumeration, minus the values + you don't need. + </para> +<example xml:id="ex-modify-attr"><title>Deleting an attribute</title> +<para>RNG</para> +<programlisting language="rng"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<grammar xmlns:db="http://docbook.org/ns/docbook" + ns="http://docbook.org/ns/docbook" + xmlns="http://relaxng.org/ns/structure/1.0"> + <include href="docbook.rng"/> + <!-- add value to an enumeration --> + <define name="db.spacing.enumeration" combine="choice"> + <value>large</value> + </define> +</grammar>]]></programlisting> +<para>RNC</para> +<programlisting language="rnc"><![CDATA[namespace db = "http://docbook.org/ns/docbook" + +include "docbook.rnc" inherit = db +# add value to an enumeration +db.spacing.enumeration |= "large"]]></programlisting> +</example> + </section> + </section> + <section xml:id="cust-naming"> + <title>Naming and versioning DocBook customizations</title> + <para> + TBD + </para> + </section> </section> @@ -1073,7 +1736,7 @@ somewhere (e.g. into a <filename>mathml</filename> subdirectory).</para> </step> <step> <para>Create a schema customization in compact syntaxâ<filename>dbmathml.rnc</filename>:</para> -<programlisting>namespace html = "http://www.w3.org/1999/xhtml" +<programlisting language="rnc">namespace html = "http://www.w3.org/1999/xhtml" namespace mml = "http://www.w3.org/1998/Math/MathML" namespace db = "http://docbook.org/ns/docbook" @@ -1087,7 +1750,7 @@ include "/path/to/docbook.rnc" { } }</programlisting> <para>Or, alternatively, you can use the XML syntax of RELAX NGâ<filename>dbmathml.rng</filename>:</para> -<programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<programlisting language="rng"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> <grammar xmlns="http://relaxng.org/ns/structure/1.0"> <include href="/path/to/docbook.rng"> @@ -1145,7 +1808,7 @@ somewhere (e.g. into an <filename>svg</filename> subdirectory).</para> </step> <step> <para>Create a schema customization in compact syntaxâ<filename>dbsvg.rnc</filename>:</para> -<programlisting>namespace html = "http://www.w3.org/1999/xhtml" +<programlisting language="rnc">namespace html = "http://www.w3.org/1999/xhtml" namespace db = "http://docbook.org/ns/docbook" namespace svg = "http://www.w3.org/2000/svg" @@ -1159,7 +1822,7 @@ include "/path/to/docbook.rnc" { } }</programlisting> <para>Or, alternatively, you can use the XML syntax of RELAX NGâ<filename>dbsvg.rng</filename>:</para> -<programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<programlisting language="rng"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> <grammar xmlns="http://relaxng.org/ns/structure/1.0"> <include href="/path/to/docbook.rng"> @@ -1209,7 +1872,7 @@ and SVG together?</para> <para>Yes, you can create a special schema customization that combines both MathML and SVG with the DocBook schema. In compact syntax, the merged schema is:</para> -<programlisting>namespace html = "http://www.w3.org/1999/xhtml" +<programlisting language="rnc">namespace html = "http://www.w3.org/1999/xhtml" namespace mml = "http://www.w3.org/1998/Math/MathML" namespace db = "http://docbook.org/ns/docbook" namespace svg = "http://www.w3.org/2000/svg" @@ -1225,7 +1888,7 @@ include "/path/to/docbook.rnc" { } }</programlisting> <para>Or alternatively in the full RELAX NG syntax:</para> -<programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<programlisting language="rng"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> <grammar xmlns="http://relaxng.org/ns/structure/1.0"> <include href="/path/to/docbook.rng">