CP RSS Channel
About Our Sponsors
Articles & Papers
Technology and Society
[August 23, 2001] The purpose of this committee [OASIS DocBook Technical Committee] is to develop and maintain the DocBook family of specifications. In particular, this TC maintains the XML and SGML DocBook DTDs, a suite of extension modules, and a simplified authoring subset of DocBook. The TC may also support other schema languages in the future and may develop additional modules and derived document types. The DocBook TC will also develop specifications based on previously published standards for use in the XML version of DocBook and other related XML specifications; the first such specification will be based on previously published ISO 9573 entity sets (themselves an extension of the ISO 8879 entity sets). [Revised OASIS DocBook TC Charter, 2001-08-23]
[February 02, 2001] Karl Best announced that "the ballot for the DocBook v4.1 Committee Specification has passed, and [so] the submission is now an OASIS Specification."
[August 30, 2000] Norman Walsh (Chair, DocBook Technical Committee) announced the release of the DocBook XML DTD Version 4.1.2 (27-Aug-2000). Version 4.1.2, principally a maintenance release, is the current XML version of DocBook; The XML DTD has been in development beginning with version 4.0. The EBNF Module is an extension to DocBook XML V4.1.2; it adds support for EBNF (extended Backus-Naur form) diagrams. Other extensions: the MathML Module adds support for MathML in equation markup; the HTML Forms Module adds support for HTML Forms markup. DocBook "is a DTD maintained by the DocBook Technical Committee of OASIS. It is particularly well suited to books and papers about computer hardware and software, though it is by no means limited to these applications. The DocBook Technical Committee maintains both SGML and XML versions of the DocBook DTD. To the extent that it is practical, these DTDs are identical. There is no intentional difference between the DTDs, they are supposed to accept the same set of documents. Because it is a large and robust DTD, and because its main structures correspond to the general notion of what constitutes a 'book,' DocBook has been adopted by a large and growing community of authors writing books of all kinds. DocBook is supported 'out of the box' by a number of commercial tools, and there is rapidly expanding support for it in a number of free software environments. These features have combined to make DocBook a generally easy to understand, widely useful, and very popular DTD. Dozens of organizations are using DocBook for millions of pages of documentation, in various print and online formats, worldwide." DocBook: The Definitive Guide (Norman Walsh) provides a complete resource for understanding and implementing the DocBook DTD. For other references, see (1) the DocBook FAQ and (2) "DocBook XML DTD."
General: News, Articles, Papers, Reports
[October 22, 2005] Eliot Kimber: How Did You Decide Between DocBook, DITA, or Custom DTDs? October 12, 2005. Linda L. Talboo asked on the Adepters list and on the Yahoo!Groups 'dita-users' list: "We are in the planning stages of switching to Arbortext Editor (formerly Epic Editor). Our current dilemma is whether to use DocBook, DITA, or custom DTDs. A major consideration is the ability to create books in Arbortext. We would need to create table of contents, indexes, and glossaries. We are leaning towards using DITA DTDs, because we eventually plan to feed information into a Content Management System, and DITA seems to be much better at 'chunking' than DocBook. Has any user had experience with DITA, books, and Arbortext? What factors influenced your decision to use DocBook, DITA or custom DTDs?" Eliot Kimber composed a response: "A custom document type should, of course, give you the best fit to your specific requirements (although its easy enough to go wrong there). But of course the startup cost is high. While I like nothing more than to do ground-up engineering of document types and the systems that support them, it's still a fact that both DocBook and DITA reflect years of collective wisdom and practice in using SGML and XML for technical documentation and therefore using them helps to minimize the risk that your system will go horribly wrong. While both have their warts, they're both clearly good enough for a wide range of applications and both are designed to be adapted to local requirements... [much text deleted]... The advantage of starting with a DocBook or DITA base instead of from scratch is that the initial cost of entry is much lower — you can start doing something even if it's not optimal with very little investment. However, to produce a complete production system that is optimized for your specific requirements and business processes, you will eventually spend about as much as you would have with a from-scratch system (remember the 80/20 rule always holds). As for whether to start with DocBook or DITA, my standard guidance is: (1) If you need to get started immediately, want to initially invest as close to zero as you can, and your primary task is to produce typical technical manuals, use DocBook. (2) If you have any requirement for re-use, specialization, or modular delivery AND you can afford a little up-front investment in analysis, specialization, and tool development, then use DITA..."
[October 22, 2005] "DITA for DocBook: Implementing the Darwin Information Typing Architecture for DocBook." By Norm Walsh. Blog. Volume 8, Issue 136 (21-October-2005). "...DocBook and DITA are competitors, at least to the extent that both are aimed at the technical documentation market. I think DITA can point to four technical differences that are arguably features in its favor: (1) A topic-oriented authoring paradigm. (2) A cross-referencing scheme that's more practical than XML's flat ID space. (3) SGML's conref, reinvented; (4) An extensibility model based on specialization... DocBook's legacy is certainly big, linear documents: it even has the word 'book' in it's name. But there's nothing that prevents you from writing modern, topic-oriented, highly modular documentation in DocBook. Nothing except, perhaps, the emotional weight of the tag names... With a couple of hours of hacking [using RELAX NG + XSLT], I've implemented on top of DocBook the four key features of DITA that I could identify... In doing so, I've attempted to remain true to the spirit of DocBook, so my content models aren't exactly the same as the DITA models, but I think the analogies are sound. That means the choice of which vocabulary to use, DocBook or DITA, comes down simply to the actual terms in the vocabulary, the elements and attributes provided, their semantics, and their relationships to each other... My experiment to implement DITA on top of DocBook includes: (1) A schema (RNG or RNC) — The schema is a DocBook 5.0 extension that defines a new top-level element, the <topic>. In the interest of modelling DITA, it also defines a <task> with the same general structure as a DITA task, a <concept>, and a <reference> as specializations of <topic>. (2) A stylesheet — The stylesheet is a customization of the DocBook XSLT2 Stylesheets. It handles the semantics of the simple map files I outlined above, supports conref, and implements the DITA fragment identifier syntax. I incorporated the schema support into the base stylesheets. (3) An example — My example is just a toy, but it has several parts: a map, a 'main' topic, a 'subordinate' topic, and a task..."
"The DocBook DTD as XML," by Norman Walsh. "Converting the DocBook DTD to XML is much more challenging than dealing with the instances. . ." An excerpt from DocBook in a Nutshell, by Norman Walsh and Leonard Muellner (Sebastopol, CA: O'Reilly & Associates, Inc., [forthcoming] "Summer 1998"). [Version 0.4 archive copy, 980316] [local archive copy v 0.3, 980310]
Walsh, Norman; Muellner, Leonard. DocBook: The Definitive Guide. The Official Documentation for DocBook. Sebastopol, California: O'Reilly and Associates, 1999. Extent: xiv + 638 pages, CDROM. ISBN: 1-56592-580-7. "This book is the complete and official documentation of the DocBook Document Type Definition (DTD) and many of its associated tools. DocBook is a system for writing structured documents using SGML and XML. DocBook, provides all the elements you'll need for technical documents of all kinds. A number of computer companies use DocBook for their documentation, as do several Open Source documentation groups, including the Linux Documentation Project (LDP). With the consistent use of DocBook, these groups can readily share and exchange information. With an XML-enabled browser, DocBook documents are as accessible on the Web as in print." See the Web site and the book announcement.
[August 18, 2003] "DocBook for Eclipse: Reusing DocBook's Stylesheets." By Jirka Kosek. From XML.com (August 13, 2003). ['Use XSLT to integrate your own documentation into the Eclipse IDE.'] "DocBook is a popular tool for creating software documentation among developers. One reason for its success is the existence of the DocBook XSL stylesheets, which can be used to convert DocBook XML source into many target formats including HTML, XHTML, XSL-FO (for print), JavaHelp, HTML Help, and man pages. The stylesheets can be further customized to get other outputs as well. In this article I am going to show you how easily you can integrate DocBook documents into the Eclipse platform help system by reusing existing stylesheets... auxiliary help files are usually XML or HTML-based, so we can use XSLT to generate them. If you have your documentation in DocBook and you want to feed it into the help system, the only thing you need is to extend the existing stylesheets to emit the auxiliary files together with a standard HTML output. That is even easier if you reuse some existing DocBook XSL stylesheet templates. The whole Eclipse platform is developed around the idea of plugins. If you want to contribute your help documents to the Eclipse platform, you have to develop a new help plugin. The plugin is composed of the HTML and image files, the table of contents file in XML, and the manifest file... As the Eclipse help is based on HTML, we can reuse existing stylesheets that generate multiple HTML files from DocBook XML source. However, we need to extend these stylesheets to generate the table of contents file and the manifest file... Software documentation is an area where you can very effectively use XML and XSLT to do multichannel publishing. If you stick to using a well-known and standardized vocabulary like DocBook, you can benefit from usage of existing stylesheets and other conversion tools. If you want to plug your DocBook documentation into some new help format, you can quite easily hack existing stylesheets to generate a new output format. The method for creating output for the Eclipse platform help described in this article can be used for almost any HTML based online help system..."
[May 21, 2002] "The DocBook Document Type." Version 4.2 Candidate Release 2. OASIS DocBook Technical Committee Working Draft. 21-May-2002. "DocBook is general purpose XML and SGML document type particularly well suited to books and papers about computer hardware and software (though it is by no means limited to these applications). The DocBook Technical Committee maintains the DocBook schema. DocBook is officially available as a Document Type Definition (DTD) for both XML and SGML. It is unofficially available in other forms as well. The Version 4.2 release is a maintainance release. It introduces no backwards-incompatible changes. All valid DocBook 4.1 documents are also valid DocBook 4.2 documents..." [Norman Walsh announced the availability of the second Candidate Release of DocBook V4.2. "Please give it a try and report the results of your efforts. If no errors are reported in the next 30 days, the TC will be able to vote to move it to Committee Specification status." The The DocBook SVG Module Version 1.0 Beta 2 is also available [OASIS DocBook Technical Committee, Working Draft 21-May-2002]. "This module integrates SVG (Scalable Vector Graphics) into DocBook by incorporating the SVG V1.1 DTD using a namespace prefix and extending the content model of DocBook's imageobject element to allow those elements to occur."
[March 21, 2002] "DocBook V4.2 Release Candidate 1." Posted by Norman Walsh for the OASIS DocBook Technical Committee. DocBook "is general purpose XML and SGML document type particularly well suited to books and papers about computer hardware and software (though it is by no means limited to these applications)... The DocBook Technical Committee is pleased to announce the release of DocBook V4.2 Release Candidate 1 in XML and SGML. DocBook V4.2 incorporates numerous enhancements over DocBook V4.1 and DocBook XML V4.1.2. These changes are documented in the DocBook Document Type specification. Development of DocBook V4.2 is 'finished'. The purpose of the Candidate Release phase is to encourage widespread testing of the latest DocBook release. If no problems are reported in the next 30 days, the DocBook Technical Committee plans to advance DocBook V4.2 to Committee Specification status. Please give DocBook V4.2 a try in your favorite tools and report any problems that you encounter to the email@example.com mailing list."
[December 20, 2001] "Conceptual Model for Processing DocBook SGML and XML." By Nik Clayton (FreeBSD Documentation Project). This "maps out the relationships between the various components in the FreeBSD DocBook pulishing toolchain (used to generate high quality PS, PDF, TXT, PDB, RTF, and HTML output). I thought it might be useful for people who are trying to understand how the various technologies and tools fit together..." Reviewers may email Nik Clayton for information on a sample implementation of the infrastructure which supports this processing framework. [cache]
[July 21, 2001] "Take My Advice: Don't Learn XML." By Michael Smith (Moderator, xml-doc mailing list). In O'Reilly News July 18, 2001. "If document authoring is important to you (you're a technical writer, an HTML markup author, manager of a documentation group, an anonymous pamphleteer) and you're trying to decide whether it would be worthwhile for you to learn XML and use it for authoring documents, stick around. What you learn might save you a lot of time and spare you from some unnecessary frustration... Why not learn XML? The short answer is: because 'learning XML' is a complicated task -- a chore much more complicated than learning, say, HTML, and one that you don't need to put yourself through if you're just looking for a better system for document authoring. So instead of learning XML, I recommend that you complete the following alternate course of study, which I've organized into just three easy 'lessons'... I'm sure you've already heard plenty of hype about the value of learning XML, so I don't expect you to simply make a leap of faith and take my word for it when I tell you that learning DocBook or TEI5 or some other specific markup dialect (instead of learning about XML in general) may very well be the best route to the document-authoring solution you've been looking for. I reckon that to be convinced, you probably want to know some details. So that's what I'll try to provide in the remainder of this lesson, using DocBook as an example, because it's my preferred dialect... I wrote this article not only to try to sell other document authors on what I see as the value of learning DocBook, but also to elicit some further discussion."
[March 06, 2001] "Introducing DocBook." By Norman Walsh. 5 Mar 2001 or later. "I've put the slides from my "Introducing DocBook" presentation online... This material was originally presented by Norman Walsh on 7-Mar-2001 at the WinWriters Online Help Conference in Santa Clara, CA. [*1] The slides were produced from a single XML source document using XSLT. The presentation of these slides uses Cascading Style Sheets; for best results, use a browser which can display CSS formatting. You can page through the slides one at a time, or use the frames view which offers a simultaneous table of contents.  Well, supposed to have been presented, actually. I was unable to travel to Santa Clara due to inclement weather."
[April 16, 2001] "The Design of the DocBook XSL Stylesheets." By Norman Walsh (XML Standards Engineer Sun Microsystems, Technology Development Center). Paper presented at XSLT-UK 01 (08 Apr - 09 Apr 2001, Keble College, Oxford, England). 08-April-2001. Version 1.0. "Building stylesheets for a large, rich XML vocabulary is a challenging exercise. This paper explores some of the design issues confronted by the author in designing XSL stylesheets for DocBook, an XML DTD maintained by the DocBook Technical Committee of OASIS. It is particularly well suited to books and papers about computer hardware and software (though it is by no means limited to these applications). DocBook consists of nearly 400 tags. The HTML and Formatting Object stylesheets each consist of roughly 1000 templates spread over about 30 files. The design for the DocBook XSL Stylesheets attempts to meet the following goals: (1) Full support for all of DocBook. (2) Full support for both HTML and XSL Formatting Object presentations. (3) Utility for a wide range of users, with varying levels of technical skill. (4) Support across diverse hardware and software platforms. (5) Provide a framework on top of which additional stylesheets can be written for schemas derived from DocBook. (6) Support for internationalization. (7) Support for a wide range of projects (books, articles, online- and print-centric presentations, etc.) Although not all of these goals have been completely achieved, progress has been made on all of them. Five techniques stand out as important factors in achieving these goals: modularity, parameterization, self-customizing stylesheets, 'literate' programming, and extensions. The rest of this paper will discuss these techniques in detail... [Conclusion:] XSL Transformations and Formatting Objects are a rich platform on which to build stylesheets for large, sophisticated XML vocabularies. Designing stylesheets that will be adaptable and maintainable is an interesting software engineering challenge. In this paper we've examined five factors that contribute to the successful design of XSL stylesheets: modularity, parameterization, stylesheet generation, documentation, and XSLT extensions." References: (1) "SGML/XML and Literate Programming" (2) "Extensible Stylesheet Language (XSL/XSLT)."
[October 05, 2000] Linux Documentation Project to Use DocBook XML for Authoring. A thread on the LDP DocBook mailing list (noted by Michael Smith) indicates the decision of the Linux Documentation Project (LDP) to officially support authoring and publishing technical documentation using the XML version (4.1.2) of the DocBook -- in addition to the SGML DTDs (Linuxdoc, DocBook v3.x, DocBook v4.x) they already support. The Linux Documentation Project "is working on developing free, high quality documentation for the GNU/Linux operating system. The overall goal of the LDP is to collaborate in all of the issues of Linux documentation. This includes the creation of 'HOWTOs' and 'Guides'. The LDP's Author Guide has specified (hitherto) that all HOWTO documents must be in one of the two SGML formats: LinuxDoc or DocBook; in the current mode of production, DSSSL stylesheets are used to create output from the DocBook SGML source. The DocBook DTD, maintained in SGML and XML versions by the DocBook Technical Committee of OASIS, "has been adopted by a large and growing community of authors writing books of all kinds. DocBook is supported 'out of the box' by a number of commercial tools, and there is rapidly expanding support for it in a number of free software environments. These features have combined to make DocBook a generally easy to understand, widely useful, and very popular DTD. Dozens of organizations are using DocBook for millions of pages of documentation, in various print and online formats, worldwide."
[January 13, 2001] Schemas for DocBook: W3C XML Schema, RELAX, and TREX. Norm Walsh (Sun Microsystems) recently announced the (alpha) release of schemas for DocBook, including W3C XML Schema, RELAX, and TREX. "I have just updated the experimental XML Schema for DocBook. You can get the new version (and the ChangeLog) at http://www.oasis-open.org/docbook/xmlschema/22.214.171.124/. ['The DocBook XML Schema V126.96.36.199 attempts to be an accurate translation of the DocBook XML V4.1.2 DTD. In this version, the parameterization of the schema is roughly identical to the parameterization of the DTD. This may change as I begin to experiment with the construction of derivative schemas.'] I have also produced a RELAX schema for DocBook V4.1.2, although I have no tool that validates all of RELAX so, while I believe it is correct, I can't demonstrate it; see http://www.oasis-open.org/docbook/relax/188.8.131.52/. Finally, I produced a TREX schema from the RELAX schema. I tweaked it a bit by hand (removing a few redundancies), so it's not quite a simple mechanical transformation. See http://www.oasis-open.org/docbook/trex/184.108.40.206/. Norm also released a preliminary version of the JRefEntry DTD, which represents a customization of the DocBook RefEntry model: "the purpose of this customization is to mirror the order and nature of structured comment tags in JavaDoc documentation." See the JRefEntry web page for details.
[November 08, 2000] Norman Walsh (Chair, DocBook Technical Committee) announced a provisional draft DocBook XML Schema, available on the Sun Microsystems DeveloperConnection web site. Norm writes: "The DocBook XML Schema Version 220.127.116.11 attempts to be an accurate translation of the DocBook XML V4.1.2 DTD. In this version, the parameterization of the schema is roughly identical to the parameterization of the DTD. This may change as I begin to experiment with the construction of derivative schemas. [This] DocBook XML Schema V18.104.22.168 'Alpha Release' is an experimental release. It validates with XSV version 1.166/1.77 of 2000/09/28 15:54:50 on my system. I welcome reports of success or failure with other XML Schema validation tools. The namespace names (URIs) used in this schema are purely imaginary. They have no official status, nor do they foreshadow the future existence of any similar official URIs. I had to use something. The DocBook XML Schema is known to differ from the DocBook DTD in the following ways: (1) There are no named character entities. You can't define those in XML Schema. (2) The table model is the OASIS Exchange Table Model, not the CALS Table Model. This table model is less rich than the CALS model, lacking spanspec, tfoot, and a few other things. (3) Inside the table model, the tgroup element and all of its descendants are in a different namespace. (4) There are bugs, perhaps dozens, possibly hundreds. With the exception of tables, which will definitely require some markup changes in the instances, documents that are valid against the DTD should be valid against this schema..." [cache]
[October 05, 2000] Karl Best (OASIS - Director, Technical Operations) recently announced that the DocBook Technical Committee "has submitted to OASIS the latest version of the DocBook DTD, and asks that the OASIS membership vote to approve it as an OASIS Specification. The submission meets the requirements of the OASIS technical committee process. The DocBook Technical Committee has submitted DocBook v4.1.2, an XML version of the DTD, and v4.1, an SGML version of the DTD, and certifies that these are valid DTDs of their type. The DTDs may be found at http://www.oasis-open.org/docbook/xml/4.1.2/ and http://www.oasis-open.org/docbook/sgml/4.1/. The submission is documented. DocBook 3.1 was fully documented by DocBook: The Definitive Guide at http://docbook.org/tdg/. The changes introduced in DocBook 4 have not yet been integrated into TDG, but they are available at http://docbook.org/tdg/40updates/... As specified by the Technical Committee Process, balloting takes place as follows: The OASIS membership has 30 days to respond to this ballot; balloting will close on 31 October 2000. One vote from each OASIS member organization is allowed; an organization may change its vote by sending in another vote up until the close of balloting..." [cache]
[November 22, 2000] "Transforming DocBook documents using XSLT. [XML Matters #5.]" By David Mertz, Ph.D. (Archivist, Gnosis Software, Inc.). From IBM DeveloperWorks. November 2000. ['Using a DocBook example, David Mertz shows how to convert an XML document to HTML through XSLT (Extensible Stylesheet Language Transformation). Along the way, your intrepid columnist discusses four alternative approaches for transforming XML documents and shares what he experienced in experimenting with some open source tools. Sample code includes fragments of XSLT documents, valid HTML outputter code in XSLT for a simple DocBook chapter, and a brief XSLT looping example.'] " There are at least four possible approaches for transforming a DocBook document -- or most any XML document -- into end-user formats. I seriously considered all four approaches for my own little project. This column discusses only the last option in detail, but all are worth keeping in mind as you plan a project that involves repeated transformations: (1) Write custom transformation code. It would be nice to start with a programming language that has some libraries for basic XML methods like SAX and DOM. But even assuming the basic parsing is a black box, custom code can do whatever you want with the parsed elements. Ultimately, this is the most flexible and powerful approach, but it is also likely to take more work, both up front and in maintenance. (2) Use Cascading Stylesheets with our DocBook document. It's a thought.... (3) Use Document Style Semantics and Specification Language (DSSSL) to specify transformations into target formats. On the plus side, a number of DSSSL style sheets already exist for DocBook (and for other formats). DSSSL is basically a whole new programming language to learn, and it's a functional Lisp-like language to boot... (4) Use eXtensible Stylesheet Language Transformations (XSLT). In one sense, XSLT is actually a specification for a class of XML documents. That is, an XSLT style sheet is itself a well-formed XML document with some specialized contents that let you "templatize" the output format you are looking for (stay tuned for what this means). A large number of tools at least nominally support XSLT: My hunch is that this really is the direction technologies are going in for XML transforms -- either because of, or in spite of, its "official" status with the W3C. XSLT can specify transforms to any target format. But the general feeling I've picked up is that most developers find it easiest to work with XSLT when the target format is another XML format, such as XHTML... Also in PDF.
[November 01, 2000] "Getting Comfortable with the DocBook XML Dialect. [XML Matters #4.]" By David Mertz, Ph.D. (Archivist, Gnosis Software, Inc.). From IBM DeveloperWorks. October 2000. ['This column continues the discussion of the benefits of using DocBook to convert documents in heterogeneous formats to a single, standard XML format. It also looks at some DocBook tags in greater detail and discusses how to compose a basic DocBook document.'] "If your document archives are like mine, they contain files in every format from Microsoft Word 3.3 to HTML to Word Perfect 7 to ASCII text. Often, you can't even obtain the software you used to create the original documents. Fortunately DocBook, an SGML dialect for creating all-purpose technical documents, can help you move your files into a single, standard XML format. In this column, I'll explain how to use the XML version of the DocBook DTD to convert an existing document. DocBook is a rather complex DTD with hundreds of elements. Fortunately you don't need to know all of DocBook to work with it. As you'll see, the basic elements are arranged logically, and most elements follow similar patterns for nesting child elements..."
[May 11, 1998] Norm Walsh has released Version 0.7 of the DocBook 3.0 XML DTD. This version of the DocBk30 XML DTD "corrects table-related bugs caused by failure to lowercase GIs in a couple of parameter entities in
dbpoolx.mod. Previously (April 9, 1998): Norm Walsh released the "DocBk30 XML V0.6 DTD" ("fixed one small problem with the pubid of dbgenent and fixed a few version number problems in the documentation. . . also added DTDParse documentation for the DTD."); [local archive copy]. Previously: (March 06, 1998): DocBk30 XML Version 0.3 DTD, announced by Norman Walsh on Thu, 05 Mar 1998; [local archive copy, 980306]
[February 19, 1998] Posting from Terry Allen for availability of an XML [sample document] version of Docbook that . . . conforms to the 6/30 draft of XML-LANG. See also "DocBk30 XML DTD", as of 980219. [archive copy]
See also: Frequently Asked Questions about DocBook and DocBook RFEs.
docbook-tools - "a pretty good prepackaged setup of DocBook for Linux called 'docware' or 'docbook-tools' at http://sourceware.cygnus.com/docbook-tools/. docbook-tools is being used for the documentation of the GNOME project. It's based on DocBook v3.0, but the install-catalog script makes it easy to drop in a newer version of the DTD and stylesheets if you want. Also included are some nice db2X scripts." [Jonathan F. Dill]
Davenport Group: DocBook DTD. See this section for the SGML DocBook DTD and early references.
|Receive daily news updates from Managing Editor, Robin Cover.|