From: Dick Hamilton Date: Wed, 23 Jan 2008 00:55:50 +0000 (+0000) Subject: Copy edit for spelling, typos and minor grammatical X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=9ae1ba111916bd00d15439bd4d147223b2572ef2;p=docbook-dsssl Copy edit for spelling, typos and minor grammatical glitches. Updated the link to the xsl2 stylesheet snapshot. --- diff --git a/docbook/relaxng/docbook/howto/howto.xml b/docbook/relaxng/docbook/howto/howto.xml index 5dd2a4dc2..7f36f7a25 100644 --- a/docbook/relaxng/docbook/howto/howto.xml +++ b/docbook/relaxng/docbook/howto/howto.xml @@ -41,19 +41,19 @@ switching from DocBook V4.x to DocBook V5.0. It describes differences between DocBook V4.x and V5.0 and provides some suggestions about how to edit and process DocBook V5.0 documents. There is -also section devoted to conversion of legacy documents from DocBook +also a section devoted to conversion of legacy documents from DocBook 4.x to DocBook V5.0. -At the time of this writing the current version of DocBook V5.0 -was &version;. However, almost all information in this document is -general and it is applicable to any newer version in DocBook V5.0 -series. +At the time this was written the current version of DocBook V5.0 +was &version;. However, almost all of the information in this document is +general and applies to any newer version of DocBook V5.0. +
Introduction The differences between DocBook V4.x and V5.0 are quite radical in -some aspects, but the basic idea behind DocBook is still the same and +some aspects, but the basic idea behind DocBook is still the same, and almost all element names are unchanged. Because of this it is very easy to become familiar with DocBook V5.0 if you know any previous version of DocBook. You can find a complete list of changes in @@ -94,7 +94,7 @@ element is now uniquely identified by its local name and namespace. The namespace name http://docbook.org/ns/docbook serves only as an identifier. This resource is not fetched during processing -of DocBook documents and you are not required to have an Internet +of DocBook documents, and you are not required to have an Internet connection during processing. If you access the namespace URI with a browser, you will find a short explanatory document about the namespace. In the future this document will probably conform to (some version of) RDDL @@ -107,7 +107,7 @@ and provide pointers to related resources. Relaxing with DocBook For more than a decade, the DocBook schema was defined using a -DTD. However DTDs have serious limitations and DocBook V5.0 is thus +DTD. However, DTDs have serious limitations, and DocBook V5.0 is thus defined using a very powerful schema language called RELAX NG. Thanks to RELAX NG, it is now much easier to create customized versions of DocBook, and some content models are now cleaner and more @@ -126,7 +126,7 @@ DTD. 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd'>
Sample article - This is really very short article. + This is a very short article.
]]> @@ -140,7 +140,7 @@ attribute instead.
Sample article - This is really very short article. + This is a very short article.
]]> @@ -171,32 +171,31 @@ technical reasons: -DocBook V4.x is feature frozen. At the time -of this writing DocBook V4.5 is the last version of DocBook in the V4.x -series. Any new DocBook development, like the addition of new elements, will -be done in DocBook V5.0. It is only matter of time before useful, new -elements will be added into DocBook V5.0, but they are not likely to be -back ported -into DocBook V4.x. DocBook V4.x will be in maintenance mode -and errata will be published if necessary. +DocBook V4.x is feature frozen.DocBook V4.5 +is the last version of DocBook in the V4.x series. Any new DocBook +development, like the addition of new elements, will be done in +DocBook V5.0. It is only matter of time before useful, new elements +will be added into DocBook V5.0, but they are not likely to be back +ported into DocBook V4.x. DocBook V4.x will be in maintenance mode and +errata will be published if necessary. -DocBook V5.0 offers new functionality. Even -the current version of DocBook V5.0 provides significant improvements -over DocBook V4.x. For example there is general markup for annotations, -a new and flexible system for linking, and unified markup for information -sections using the info element. +DocBook V5.0 offers new functionality. +DocBook V5.0 provides significant improvements over DocBook V4.x. For +example there is general markup for annotations, a new and flexible +system for linking, and unified markup for information sections using +the info element. DocBook V5.0 is more extensible. Having DocBook V5.0 in a separate namespace allows you to easily mix DocBook -markup with other XML based languages like SVG, MathML, XHTML or even +markup with other XML-based languages like SVG, MathML, XHTML or even FooBarML. DocBook V5.0 is easier to customize. RELAX NG offers many powerful constructs that make customization much easier -than it would be using a DTD. +than it would be using a DTD (see ). @@ -209,9 +208,9 @@ than it would be using a DTD. (or the mirror at ). Only the RELAX NG schema is normative -and it is preferred over the other schema languages. However, for your +and it is preferred over the other schema languages. However, for your convenience there are also DTD and W3C XML Schema versions provided for DocBook -V5.0. But please note that neither DTDs nor XML schemas are able to +V5.0. But please note that neither the DTD nor the W3C XML schema are able to capture all the constraints of DocBook V5.0. This mean that a document that validates against the DTD or XML schema is not necessarily valid against the RELAX NG schema and thus may not be a valid @@ -223,18 +222,18 @@ that don't support RELAX NG. Authors are encouraged to switch to RELAX NG based tools as soon as possible, or at least to validate documents against the RELAX NG schema before further processing. -Some document constrainst can't be expressed in schema languages +Some document constraints can't be expressed in schema languages like RELAX NG or W3C XML Schema. To check for these additional -constraints DocBook V5.0 uses Schematron. It is recommended to -validate your document not only against RELAX NG schema but also -against Schematron schema. +constraints DocBook V5.0 uses Schematron. We recommend that you +validate your document against both the RELAX NG and +Schematron schemas.
Where to get the schemas The latest versions of schemas can be obtained from . At the time of this -writing the latest version is &version; and individual schemas are +xl:href="http://docbook.org/schemas/5x.html"/>. At the time this was +written the latest version was &version;. Individual schemas are available at the following locations: @@ -274,9 +273,9 @@ xl:href="http://docbook.org/tdg5/en/html/pt02.html">the reference part of DocBook: The Definitive Guide. -Other parts of the book have not yet been updated to reflect the -changes made in DocBook V5.0. Please do not be confused by -this. +Other parts of DocBook: The Definitive +Guide have not yet been updated to reflect the changes +made in DocBook V5.0. Please do not be confused by this.
@@ -294,7 +293,7 @@ process content stored in DocBook V5.0.
Editing DocBook V5.0 -Because DocBook is an XML based format and XML is a text based +Because DocBook is an XML-based format and XML is a text-based format, you can use any text editor to create and edit DocBook V5.0 documents. However, using dumb editors like Notepad is not very productive. You will do better if you use an editor that @@ -346,7 +345,7 @@ with the corresponding DocBook V5.0 grammar. If you can't edit the global schemas.xml file, -you can create this file in a directory with your document. nXML will +you can create this file in the same directory as your document. nXML will find associations placed there also. In this case you must create a complete configuration file like: @@ -398,8 +397,8 @@ oXygen with both DocBook V4.x and DocBook V5.0. Now you can close the preference box by clicking on the -OK button. From this time oXygen will assist -you with writing DocBook V5.0 content and you will be able to validate +OK button. oXygen will assist +you with writing DocBook V5.0 content, and you will be able to validate your documents against both RELAX NG and Schematron schemas.
@@ -432,11 +431,11 @@ provides everything you need to edit DocBook V5.0 documents.
In order to use DocBook V5.0 in XXE you have to install -correspoding add-on. Go to +an add-on. Go to OptionsInstall Add-ons…. Then choose DocBook -5 configuration and press OK -button. After restart XXE is ready to work with DocBook V5.0 +5 configuration and press the OK +button. After restart, XXE is ready to work with DocBook V5.0 documents.
@@ -446,16 +445,16 @@ documents.
Validating DocBook V5.0 -If you are not using a RELAX NG based validating editor when you +If you are not using a RELAX NG-based validating editor when you create documents, we strongly recommend that you validate your documents against RELAX NG and Schematron schemas before processing -them. Only after successful validation you can be sure that your +them. Only after successful validation can you be sure that your document is really DocBook V5.0 and that processing tools will be able to process it correctly. For validation you can use tools that support simultaneous RELAX NG and Schematron validation, or you can use NVDL to orchestrate validation using -those two schemas. +the two schemas.
Using RELAX NG and Schematron @@ -488,7 +487,7 @@ To install and use MSV follow these steps: of the Java virtual machine. This is necessary because the DocBook schema is quite large. If you get stack overflow errors from MSV, increase this value. You may get spurious error messages if the value -is too small, so if you get a stack overflow error, ignore other error +is too small, so if you get a stack overflow error, ignore any other error messages and try a larger value for the stack size. If you are not using Sun's Java implementation, please consult the documentation for your virtual machine to learn how to increase the stack @@ -507,14 +506,14 @@ RELAX NG schema with embedded Schematron rules.
Using NVDL -NVDL is a metaschema language which can send a document to -validation against several schemas. DocBook V5.0 comes with a NVDL -schema which defines that DocBook documents should be validated +NVDL is a meta-schema language which can validate a document +against several schemas. DocBook V5.0 comes with a NVDL +schema which specifies that DocBook documents should be validated against both RELAX NG and Schematron schemas. You can find a list of NVDL validators at . The following procedures show how to -install and use oNVDL and JNVDL validators. @@ -576,8 +575,8 @@ versions of the stylesheets are also able to process DocBook V5.0 with some limitations. You can process DocBook V5.0 documents with the DocBook XSL -stylesheets in exactly the same way as you process DocBook V4.x documents. -You do not need special software, you can stick to your preferred +stylesheets in exactly the same way you process DocBook V4.x documents. +You do not need special software; you can stick to your preferred XSLT processor, be it Saxon, xsltproc, Xalan or whatever else (but see the note about the lost base URI below). @@ -632,7 +631,7 @@ message is generated: xl:href="https://sourceforge.net/project/showfiles.php?group_id=21935&package_id=219178" >docbook-xsl-ns package. They are the recommended XSLT 1.0 stylesheets to use for transforming -namespaced (DocBook 5) documents. +namespaced (DocBook V5.0) documents.
@@ -654,7 +653,7 @@ documents) with external bibliographies and glossaries; no need for (most) external extensions; internationalized indexes; -easy to customize titlepage templates; +easy to customize titlepage templates. The XSLT 2.0 based stylesheets are still under development. At @@ -666,7 +665,7 @@ have, there's no specific schedule. There are not very many XSLT 2.0 implementations available. But, if you want to try the new stylesheets, grab a snapshot of the development version from +xl:href="http://docbook.sourceforge.net/snapshots/docbook-xsl2-snapshot.tar.bz2"/> and unpack it somewhere. Then download and install Saxon 9 from . @@ -1382,7 +1381,7 @@ db.author |= dbx.person]]> two new inline elements for writing about assembly language, register and instruction. - We will allow them whereever programming inlines + We will allow them wherever programming inlines or operating system inlines are allowed. defines the two elements, creates a new named pattern @@ -1876,13 +1875,13 @@ implementation) be maintained and improved in the future since work on a new XSLT 2.0 based implementation has started? -Yes, the current stylesheets (like 1.69.1) will be supported and +Yes, the current stylesheets (like 1.73.x) will be supported and improved further because they are very widely deployed and work with many existing XSLT processors. Surely there will be a point in a future when all new development will be switched to the XSLT 2.0 based implementation. But this will not happen until all features of the current stylesheets are -implemented in the new stylesheets and until there is more than +implemented in the new stylesheets, and until there is more than one usable XSLT 2.0 processor available.