Very simple book

+ 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 by 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.The examples in this section use + docbook.rng as the schema location. If you want + to create a portable schema customization you should use a standard + web-accessible location like + http://docbook.org/xml/&version;/rng/docbook.rng and + then use XML + catalogs to resolve this location to your local copy of the + schema for improved performance. Unfortunately, at the time of + this writing not all RELAX NG validators support XML catalogs. + All of the examples are given in both RNG and RNC form. +Empty customization file + + + + + + +]]> + + + +

+ 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 + + + + + + + + + + + + + + +]]> + + + + 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 wherever 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + +]]> + + +

+ 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 + + + + + + + + +]]> + + +

+ 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 + + + + + + + + + + + + + + + + + + +]]> + + + + + 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 + + + + + + + + + + + + + + + + + + +]]> + + + + 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 + + + + + + + + + + + + + + + + + + +]]> + + +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 + + + + + + + +]]> + + + + 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 + + + + + + large + +]]> + + +

+ +

+Naming and versioning DocBook customizations + +DocBook V5.0 is not tightly coupled with some particular +validation technology like DTDs. This also means that DocBook V5.0 +documents don't have to (and usually don't) start with a +document type declaration (<!DOCTYPEâ¦>) to specify the schema +(DTD) to use. Instead, DocBook V5.0 instances can be easily +distinguished from other XML vocabularies by using elements in the +http://docbook.org/ns/docbook namespace. This namespace is +enough to distinguish DocBook from other XML based formats. But the +DocBook schema evolves over time and there are several versions of +DocBook (e.g. 3.1, 4.2, 4.5 and 5.0). Since DocBook version 5.0, the +actual version used is indicated in the version attribute on a root element. + + + â¦ +]]> + +Future versions of DocBook documents will start with the same +markup, except the version number will be raised, for example to 5.1 +or 6.0. +The namespace will remain the same until the semantics of the elements +change in a backward incompatible way, which is very unlikely to happen. + +If you create a DocBook schema customization you must change the version attribute to distinguish your +customization from the official DocBook. Changing the +namespace is not recommended because that would break the processing +tools. Remember that changing namespaces is the same as renaming all +elements in the namespace. + +When you customize the schema, use the following syntax to +identify your DocBook derivation: + +base_version-[subset|extension|variant] [name[-version]?]+ + +For example: + +5.0-subset simplified-1.0 +5.0-variant ASMBook +5.0-variant ASMBook-2006 +5.0-extension MathML-2.0 SVG-1.1 + +The first part of the version identifier is the version number of the +DocBook schema from which you derived your customization. + +If your schema is a proper subset, you can advertise this status +by using the subset keyword in the description. If +your schema contains any markup model extensions, you can advertise +this status by using the extension keyword. If +you'd rather not characterize your variant specifically as a subset or +an extension, use the variant keyword. + +After these keywords you may add a whitespace separated list of +customization identifiers. Each name may be optionally followed by its +version number. + +

+ +