From: Dick Hamilton 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 @@ §convert4to5, proofreading Dick Hamilton rlhamilton@frii.com - §changes-removed, proofreading + §changes-removed, customization, proofreading +2006-04-04 2006-03-01 2005-12-28 2005-10-27 @@ -941,20 +942,682 @@ linkend="convert4to5"/>.
-Customizing DocBook V5.0 + Customizing DocBook V5.0 + + + + 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 + RNCTUT. + +
+ DocBook RELAX NG schema organization + + 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 hooks + into the schema that allow you to do a wide range of customization + by simply redefining one or more of the named patterns. + + + 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 imagedata and videodata + elements each have an align attribute + that takes the same set of enumerated values. Rather than + repeating those values, a single pattern, + db.halign.enumeration is referenced by + the db.videodata.align.enumeration + and db.imagedata.align.enumeration patterns, + which are in turn referenced by the + db.videodata.align.attribute + and db.imagedata.align.attribute 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. + +
Pattern Names + + Because named patterns are used extensively, the RELAX NG schema uses + several naming conventions. These are: + + + + Names have two or more parts, separated dots . + + + + + The first part of each name is the prefix db + + + + + Each element has a named pattern in the form + db.elementname. + Elements that have different content models in different + contexts will also have patterns in the form + db.context.elementname. For example, db.figure.info + defines the content model for the info element + when it appears as a child of the figure element. + Context may have several parts. + For example, db.cals.entrytbl.thead. + + + + + Most attributes have a named pattern in the form + db.attributename.attribute. + Attributes that have different content models in different + contexts will also have patterns in the form + db.context.attributename.attribute. + For example, + db.olink.localinfo.attribute defines the content + model of the localinfo attribute when + it appears in olink. + There are a few attributes that do not have individual named + patterns. For example, the effectivity attributes are grouped + into db.effectivity.attributes and not identified + separately. + + + + + Each element has a named pattern for its attribute list in + the form + db.elementname.attlist + + 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 + db.context.elementname.attlist + For example, db.html.table.attlist defines + the attribute list for the html table element and + db.cals.table.attlist defines the attribute + list for a cals table element. + + + + + Each attribute that has enumerated values has a + named pattern in the form + db.[context.]attributename.enumeration. + If the enumeration for a particular attribute depends on + context, optional context is provided. + For example, + db.verbatim.continuation.enumeration defines + the enumeration values for the + continuation attribute that is used + in verbatim contexts like screen. + Unlike elements and attributes, there is not necessarily a + named pattern for enumerated attributes outside their context. + For example, there is no db.class.enumeration + because the class attribute has + a broad and non-intersecting range of uses. + + + + + There are several different groupings of elements and attributes. + Here are the major ones: + + + inlines + + + Combinations of inline elements, for example, + db.error.inlines, which contains + db.errorcode, + db.errortext, etc. + + + + + blocks + + + Combinations of block elements, for example, + db.verbatim.blocks, which contains + db.programlisting, + db.screen, etc. + + + + + attributes + + + Combinations of attributes, for example, + db.effectivity.attributes, + which contains the attributes + arch, + condition, + conformance, etc. + + + + + components + + + High level components of the schema, for example, + db.navigation.components, which contains + db.glossary, + db.bibliography, + db.index, and + db.toc, and is used inside the + content model for chapter, appendix, + and preface. + + + + + contentmodel + + + Shared content models, for example, + db.admonition.contentmodel, which contains + the content model for tip, warning, + note, etc. + + + + + + + There are a couple of other groupings designed to minimize + duplication, but these are the most important. + + + + +
+
+
+ General customization considerations + + 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. + + + is an empty + RELAX NG customization that does nothing + except define the name spaces and include the standard DocBook schema. + The href attribute of the + include element points to + the location of the standard DocBook V5.0 schema. + All of the examples are given in both RNG and RNC form. +Empty customization file +RNG + + + + + + +]]> +RNC + + + +
+
+ Elements +
+ Adding elements + + 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. + + + + adds a new element, + person, with the same + content model as author. The new element will be + allowed to appear wherever author can appear. + + + The db.author pattern is copied + and renamed dbx.person, defining + a new element called person. + Then, the db.author pattern is redefined + to be a choice of the current value or dbx.person. + The combine attribute tells + RELAX NG to combine this pattern with the existing named + pattern. In this case, the value + of the combine attribute is + choice, which tells the parser that either + the original pattern or this new pattern is a valid match. + +Adding a new element by duplicating an existing one +RNG + + + + + + + + + + + + + + +]]> +RNC + + + + 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 author is allowed in four different + named patterns, each of which would have had to be redefined to + allow person. + 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. + + + + 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, + register and + instruction. + We will allow them whereever programming inlines + or operating system inlines are allowed. + + defines the two elements, creates a new named pattern + (dbx.asm.inlines) that contains them, and adds + that pattern to db.programming.inlines and + db.os.inlines. Since these two patterns + don't have any elements in common, the strategy used in + + would require selecting two different elements to clone, + which would be messy. + +Adding new inline elements +RNG + + + + + + + + + + + + + + + + + + + + + + + + + + + + +]]> +RNC + + +
+
+ Deleting elements + + Deleting elements is straightforward, but takes some + care and planning. deletes + the important admonition element by redefining + it with a content model of notAllowed. + Note that in this example, the redefinition is inside + the include element. + This is required for + redefinitions that completely replace an existing pattern. + + + 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 title + element, you won't be able to validate a book + because a book requires a title. + +Deleting an element +RNG + + + + + + + + +]]> +RNC + + +
+
+ Customizing the content model of existing elements + + + expands the definition of author to include two + new elements, born and + died. + The author element allows two content models, + db.person.author.contentmodel, which + defines an author who is a person, and + db.org.author.contentmodel, which + defines an author that is an organization. We will modify + db.person.author.contentmodel so that + only authors who are persons can have the new elements. +Modifying the content model of an element +RNG + + + + + + + + + + + + + + + + + + +]]> +RNC + + + + + This modification will allow instances like this: + + Babe Ruth + 02/06/1895 + 08/16/1948 +]]> +but because we only modified the content model for authors +who are human, it won't allow an instance like this, which +uses db.org.author.contentmodel: + + + Boston Red Sox + 1919 + 2004 +]]> + +
+
+
+ Attributes +
+ Adding attributes + + The simplest way to add an attribute to a single element + is to add it to the attlist pattern for that element. + + adds the optional attributes born + and died to the attribute + list for author. The db.author.attlist + named pattern is redefined with the + combine attribute set to + interleave, which interleaves the two new + optional attributes with the existing attributes on the list. + +Adding attributes +RNG + + + + + + + + + + + + + + + + + + +]]> +RNC +TBD +db.author.attlist &= + attribute born { db.date.contentmodel }? + & attribute died { db.date.contentmodel }?]]> + + + Unlike + , + allows + the new attributes to appear on any author + element, not just those using the person content model. + + + 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 db.person.author.contentmodel. + The only difference between this example and + 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. +Adding attributes; alternate method +RNG + + + + + + + + + + + + + + + + + + +]]> +RNC + + +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 +interleave block is not required for +attributes, though it does no harm. + +
+
+ Deleting attributes + + Deleting an attribute is similar to deleting an element, + except that you use the RELAX NG empty + pattern rather than notAllowed. + + deletes the linking attributes, which are collected in the + db.common.linking.attributes pattern, + by defining that pattern as empty. + +Deleting an attribute +RNG + + + + + + + +]]> +RNC + +include "docbook.rnc" inherit = db { + db.common.linking.attributes = empty +}]]> + + + Generally, empty is used when deleting + attributes and notAllowed is used when + deleting elements. + +
+
+ Changing permitted content of attributes + + + modifies db.spacing.enumeration to + add the additional value large. Note + that to remove a value from an enumeration, you need + to redefine the entire enumeration, minus the values + you don't need. + +Deleting an attribute +RNG + + + + + + large + +]]> +RNC + + +
+
+
+ Naming and versioning DocBook customizations + + TBD + +
@@ -1073,7 +1736,7 @@ somewhere (e.g. into a mathml subdirectory). Create a schema customization in compact syntax—dbmathml.rnc: -namespace html = "http://www.w3.org/1999/xhtml" +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" { } } Or, alternatively, you can use the XML syntax of RELAX NG—dbmathml.rng: - + @@ -1145,7 +1808,7 @@ somewhere (e.g. into an svg subdirectory). Create a schema customization in compact syntax—dbsvg.rnc: -namespace html = "http://www.w3.org/1999/xhtml" +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" { } } Or, alternatively, you can use the XML syntax of RELAX NG—dbsvg.rng: - + @@ -1209,7 +1872,7 @@ and SVG together? 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: -namespace html = "http://www.w3.org/1999/xhtml" +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" { } } Or alternatively in the full RELAX NG syntax: - +