From: Norman W. <nw...@us...> - 2006-05-04 18:44:20
|
Update of /cvsroot/docbook/defguide5/en/src In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv6382 Modified Files: ch05.xml Log Message: Incorporate the version attribute format discussion Index: ch05.xml =================================================================== RCS file: /cvsroot/docbook/defguide5/en/src/ch05.xml,v retrieving revision 1.2 retrieving revision 1.3 diff -u -U2 -r1.2 -r1.3 --- ch05.xml 7 Jul 2005 16:41:50 -0000 1.2 +++ ch05.xml 4 May 2006 18:26:24 -0000 1.3 @@ -8,24 +8,22 @@ </info> -<para> -<indexterm xml:id="customDocBookch05" class="startofrange" significance="normal"><primary>customizing</primary> - <secondary>DocBook DTD</secondary></indexterm> -<indexterm xml:id="DocBookcustomch05" class="startofrange" significance="normal"><primary>DocBook DTD</primary> - <secondary>customizing</secondary></indexterm> - -For the applications you have in mind, DocBook <quote>out of the -box</quote> may not be exactly what you need. Perhaps you need +<para><indexterm xml:id="customDocBookch05" class="startofrange" significance="normal"><primary>customizing</primary> + <secondary>DocBook DTD</secondary></indexterm><indexterm xml:id="DocBookcustomch05" class="startofrange" significance="normal"><primary>DocBook DTD</primary> + <secondary>customizing</secondary> +</indexterm>For the applications you have in mind, DocBook <quote>out +of the box</quote> may not be exactly what you need. Perhaps you need additional inline elements or perhaps you want to remove elements that you never want your authors to use. By design, DocBook makes this sort -of customization easy. +of customization easy.</para> + +<para><indexterm significance="normal"><primary>attributes</primary> + <secondary>DocBook DTD, customizing</secondary> +</indexterm><indexterm significance="normal"><primary>elements</primary> + <secondary>DocBook DTD, customizing</secondary> +</indexterm>This chapter explains how to make your own +<firstterm>customization layer</firstterm>. You might do this in order +to: </para> -<para> -<indexterm significance="normal"><primary>attributes</primary> - <secondary>DocBook DTD, customizing</secondary></indexterm> -<indexterm significance="normal"><primary>elements</primary> - <secondary>DocBook DTD, customizing</secondary></indexterm> -This chapter explains how to make your own <firstterm>customization -layer</firstterm>. You might do this in order to: <itemizedlist> <listitem><para>Add new elements</para></listitem> @@ -34,111 +32,95 @@ <listitem><para>Add new attributes</para></listitem> <listitem><para>Remove attributes</para></listitem> -<listitem><para>Broaden the range of values allowed in an attribute</para></listitem> -<listitem><para>Narrow the range of values in an attribute to a specific list or a fixed value</para></listitem> +<listitem><para>Broaden the range of values allowed in an +attribute</para></listitem> +<listitem><para>Narrow the range of values in an attribute to a +specific list or a fixed value</para></listitem> </itemizedlist> + +<para><indexterm significance="normal"><primary>extensions, DocBook DTD</primary> +</indexterm><indexterm significance="normal"><primary>environment</primary> +<secondary>DocBook extensions, affecting</secondary> +</indexterm>You can use customization layers to extend DocBook or +subset it. Creating a <acronym>DTD</acronym> that is a strict subset +of DocBook means that all of your instances are still completely valid +DocBook instances, which may be important to your tools and +stylesheets, and to other people with whom you share documents. An +<firstterm>extension</firstterm> adds new structures, or changes the +<acronym>DTD</acronym> in a way that is not compatible with DocBook. +Extensions can be very useful, but might have a great impact on your +environment. +</para> + +<para>Customization layers can be as small as restricting an attribute +value or as large as adding an entirely different hierarchy on top of +the inline elements. </para> -<para> -<indexterm significance="normal"><primary>extensions, DocBook DTD</primary></indexterm> -<indexterm significance="normal"><primary>environment</primary> - <secondary>DocBook extensions, affecting</secondary></indexterm> - -You can use customization layers to extend DocBook or subset -it. Creating a <acronym>DTD</acronym> that is a strict subset of DocBook means that all -of your instances are still completely valid DocBook instances, which -may be important to your tools and stylesheets, and to other people -with whom you share documents. An <firstterm>extension</firstterm> adds new -structures, or changes the <acronym>DTD</acronym> in a way that is not compatible with -DocBook. Extensions can be very useful, but might have a great impact -on your environment. -</para> -<para> -Customization layers can be as small as restricting an attribute value -or as large as adding an entirely different hierarchy on top of the -inline elements. -</para> + <section xml:id="ch05-shouldi"><info><title>Should You Do This?</title></info> -<para> -<indexterm significance="normal"><primary>stylesheets</primary> - <secondary>DTD extension, effects</secondary></indexterm> - -Changing a <acronym>DTD</acronym> can have a wide-ranging impact on the tools and -stylesheets that you use. It can have an impact on your authors and on -your legacy documents. This is especially true if you make an -extension. If you rely on your support staff to install and maintain -your authoring and publishing tools, check with them before you invest -a lot of time modifying the <acronym>DTD</acronym>. There may be additional issues that -are outside your immediate control. Proceed with caution. -</para> -<para> -That said, DocBook is designed to be easy to modify. This chapter -assumes that you are comfortable with <acronym>SGML</acronym>/<acronym>XML</acronym> <acronym>DTD</acronym> syntax, but -the examples presented should be a good springboard to learning the -syntax if it's not already familiar to you. + +<para><indexterm significance="normal"><primary>stylesheets</primary> + <secondary>DTD extension, effects</secondary> +</indexterm>Changing a <acronym>DTD</acronym> can have a wide-ranging +impact on the tools and stylesheets that you use. It can have an +impact on your authors and on your legacy documents. This is +especially true if you make an extension. If you rely on your support +staff to install and maintain your authoring and publishing tools, +check with them before you invest a lot of time modifying the +<acronym>DTD</acronym>. There may be additional issues that are +outside your immediate control. Proceed with caution. +</para> + +<para>That said, DocBook is designed to be easy to modify. This +chapter assumes that you are comfortable with +<acronym>SGML</acronym>/<acronym>XML</acronym> <acronym>DTD</acronym> +syntax, but the examples presented should be a good springboard to +learning the syntax if it's not already familiar to you. </para> </section> -<section xml:id="s-notdocbook"><info><title>If You Change DocBook, It's Not DocBook Anymore!</title></info> -<para> -<indexterm significance="normal"> + +<section xml:id="s-notdocbook"><info><title>If You Change DocBook, +It's Not DocBook Anymore!</title></info> + +<para><indexterm significance="normal"> <primary>public identifiers</primary> <secondary>DocBook DTD</secondary> <tertiary>altering</tertiary> -</indexterm>The DocBook <acronym>DTD</acronym> is usually referenced by its public identifier: -</para> -<screen> -//OASIS//DTD DocBook V3.1//EN</screen> -<para> -Previous versions of DocBook, V3.0 and the V2 variants, used the owner -identifier Davenport, rather than OASIS. -</para> -<para> -If you make any changes to the structure of the <acronym>DTD</acronym>, it is -imperative that you alter the public identifier that you use for the -<acronym>DTD</acronym> and the modules you changed. The license agreement under which -DocBook is distributed gives you complete freedom to change, modify, -reuse, and generally hack the <acronym>DTD</acronym> in any way you want, except that -you must not call your alterations <quote>DocBook.</quote> -</para> -<para> -<indexterm significance="normal"><primary>owner-identifiers</primary> - <secondary>changing (DocBook customization)</secondary></indexterm> -<indexterm significance="normal"><primary>description, changing (DocBook customization)</primary></indexterm> - -You should change both the owner identifier and the description. The -original DocBook formal public identifiers use the following syntax: -<screen> --//OASIS//<replaceable>text-class</replaceable> DocBook <replaceable>description</replaceable> V<replaceable>version</replaceable>//EN -</screen> -</para> -<para> -Your own formal public identifiers should use the following syntax in -order to record their DocBook derivation: -<screen> --//<replaceable>your-owner-ID</replaceable>//<replaceable>text-class</replaceable> DocBook V<replaceable>version</replaceable>-Based <optional>Subset|Extension|Variant</optional> <replaceable>your-descrip-and-version</replaceable>//<replaceable>lang</replaceable> -</screen> -</para> -<para>For example: -<screen> --//O'Reilly//DTD DocBook V3.0-Based Subset V1.1//EN -</screen> -</para> -<para> -<indexterm significance="normal"><primary>subsets (DocBook DTD)</primary></indexterm> -If your <acronym>DTD</acronym> is a proper subset, you can advertise this status by -using the <literal>Subset</literal> keyword in the description. If -your <acronym>DTD</acronym> contains any markup model extensions, you can advertise -this status by using the <literal>Extension</literal> keyword. If -you'd rather not characterize your variant specifically as a subset or -an extension, you can leave out this field entirely, or, if you -prefer, use the <literal>Variant</literal> keyword. -</para> -<para> -<indexterm significance="normal"><primary>dbgenent.mod file</primary></indexterm> -<indexterm significance="normal"><primary>public identifiers</primary> - <secondary>dbgenent.mod file, changing</secondary></indexterm> - -There is only one file that you may change without changing the public -identifier: <filename>dbgenent.mod</filename>. And you can add only -entity and notation declarations to that file. (You can add anything -you want, naturally, but if you add anything other than entity and -notation declarations, you must change the public identifier!) +</indexterm>Startig with DocBook V5.0, DocBook is identified by its namespace, +<uri>http://docbook.org/ns/docbook</uri>. The particular version of +DocBook to which an element conforms is identified by its +<tag class='attribute'>version</tag> attribute. If the element does not +specify a version, the version of the closest ancestor DocBook +element that does specify a version is assumed. The +<tag class='attribute'>version</tag> attribute is required on the root +DocBook element.</para> + +<para>If you make any changes to the DocBook schema, it is imperative +that you provide an alternative version identifier that you use for +the schema and the modules you changed. The license agreement under +which DocBook is distributed gives you complete freedom to change, +modify, reuse, and generally hack the schema in any way you want, +except that you must not call your alterations <quote>DocBook</quote>. +</para> + +<para>The following format is recommended:</para> + +<screen><replaceable>base_version</replaceable>-[subset|extension|variant] (<replaceable>name</replaceable>[-<replaceable>version</replaceable>])+</screen> + +<para>For example, version 1.0 of Acme Corporation's extension of +DocBook V5.0 could be identified as +â<literal>5.0-extension acme-1.0</literal>â.</para> + +<para>A document that relied on the version 3.2 of Example +Corporation's subset of DocBook V5.0, MathML 2.0, and SVG 1.1 could be +identified as: +â<literal>5.0-subset example-3.2 mathml-2.0 svg-1.1</literal>â.</para> + +<para>If your schema is a proper subset, you can advertise this status +by using the <literal>subset</literal> keyword in the version. If +your schema contains any markup model extensions, you +can advertise this status by using the <literal>extension</literal> +keyword. If you'd rather not characterize your variant specifically as +a subset or an extension, you can leave out this field entirely or, +if you prefer, use the <literal>variant</literal> keyword. </para> </section> |