DocBook

From Wikipedia, the free encyclopedia

You have new messages (last change).
DocBook
File extension: .xml, .dbk
MIME type: application/xml or application/docbook+xml
Developed by: OASIS
Type of format: markup language
Extended from: SGML, XML
Standard(s): 4.5 (June 2006),
5.0cr3 (Candidate Release, March, 2007)

DocBook is a markup language for technical documentation. It was originally intended for authoring technical documents related to computer hardware and software but it can be used for any other sort of documentation.

One of the principal benefits of DocBook is that it enables its users to create document content in a presentation-neutral form that captures the logical structure of the content; that content can then be published in a variety of formats, including HTML, PDF, man pages and HTML Help, without requiring users to make any changes to the source.

Contents

[edit] History

DocBook began in 1991 as a joint project of HaL Computer Systems and O'Reilly & Associates and eventually spawned its own maintenance organization (the Davenport Group) before moving in 1998 to the SGML Open consortium, which subsequently became OASIS. DocBook is currently maintained by the DocBook Technical Committee at OASIS. (More detail about the history of DocBook is presented in the "What is DocBook?" external link below.)

DocBook is available in both SGML and XML forms, as a DTD. RELAX NG and W3C XML Schema forms of the XML version are available. Starting with DocBook 5, the RELAX NG version is the "normative" form from which the other formats are generated.

DocBook originally started out as an SGML application, but an equivalent XML application was developed and has now replaced the SGML one for most uses. (Starting with version 4 of the SGML DTD, the XML DTD continued with this version numbering scheme.) Initially, a key group of software companies used DocBook since their representatives were involved in its initial design. Eventually, however, DocBook was adopted by the open source community where it has become a standard for creating documentation for many projects, including FreeBSD, KDE, GNOME desktop documentation, the GTK+ API references, the Linux kernel documentation, and the work of the Linux Documentation Project.

DocBook's use outside of the open source community also continues to grow. And a variety of commercial documentation-authoring tools are now shipped with some form of "off the shelf" support for DocBook.

Norman Walsh and the DocBook Project development team maintain the key application for producing output from DocBook source documents: A set of XSL stylesheets (as well as a legacy set of DSSSL stylesheets) that can generate high-quality HTML and print (FO/PDF) output, as well as output in other formats, including RTF, man pages and HTML Help.

Walsh is also the principal author of the book DocBook: The Definitive Guide, the official documentation of DocBook. This book is available online under the GFDL, and also as a print publication.

Because DocBook is XML, documents can be created and edited with any text editor, however many dedicated tools exist that simplify the process. Emacs in nXML mode comes with built-in DocBook schema information that allows users to quickly add elements or validate the document. A number of XML editing suites exist that come with DocBook schemas. There are WYSIWYG editors like XMLmind, which displays the DocBook document using CSS-based visual formatting for the individual elements.

[edit] DocBook v5.0

As of March, 2007, DocBook version 5.0 is in its 3rd candidate release. The DocBook XSL transformations can already generate content from DocBook 5.0 XML documents.

There are many changes between the older 4.x versions and the 5.0 version. Among them are that DocBook is defined by a RELAX NG + Schematron schema. While there is a W3C XML Schema + Schematron version available, it is not considered the definitive, or "normative" version of the schema. There is also a DTD available, though it lacks the power to truly validate all DocBook 5 documents.

DocBook 5 markup is not a strict superset of DocBook 4.x. Many of the redundancies that grew from DocBook's origins have been concatenated. For example, in DocBook 4.x, there were a set of info elements (bookinfo, chapterinfo, appendixinfo, etc) that describe information about that particular kind of element (book, chapter, appendix). In most cases, the contents of these elements were identical. However, because DocBook 4.x was defined by a DTD, any differences between these info elements based on their context required a new element name, as DTDs can only describe the content model of an element based on its name. RELAX NG has no such limitations, so all of these elements are called info in DocBook 5.

Because DocBook 5 is defined by a RELAX NG schema rather than a DTD (and thus without the corresponding DOCTYPE declaration), versioning became an issue. As such, in DocBook 5, the version of a document is defined by a version, which is required on the root element of a DocBook 5 document. This attribute specifies the version of DocBook 5 that the document is written against. Through Schematron rules, the schema requires that it appear on the root, though it may appear on other elements.

DocBook 5 is defined in a namespace (http://docbook.org/ns/docbook), whereas DocBook 4.x is not, as DTDs are not namespace aware. This allows DocBook 5 documents to more easily coexist with other namespaces (like SVG, MathML, etc).

In DocBook 5, almost any element can have intradocument linking and extradocument linking attributes. Also, DocBook 5's schemas have versions that explicitly allow for XInclude semantics.

DocBook 5 is not backwards compatible with DocBook 4.x. However, there does exist an XSLT transform for converting DocBook 4.x documents to DocBook 5.

[edit] Sample code

<book id="simple_book">
  <title>Very simple book</title>
  <chapter id="chapter_1">
    <title>Chapter 1</title>
    <para>Hello world!</para>
    <para>I hope that your day is proceeding splendidly!</para>
  </chapter>
  <chapter id="chapter_2">
    <title>Chapter 2</title>
    <para>Hello again, world!</para>
  </chapter>
</book>

The DocBook format, being based on XML, is readable by humans as well as computers. The format consists of tags (such as <book>, each with corresponding ending tags such as </book>), and textual content (such as "Hello world!"). The complete content of the document (a "book") has been structured into two "chapters," each with a "title" and consisting of one or more "para(graphs)." This could be continued throughout an arbitrarily-large book or any other document.

Notice how the tags indicate the structure and meaning of the content, but not its appearance. (There is nothing to say "put this paragraph in bold-face type," "center this on the page," and so-on.) This is by design. The same DocBook file can be processed into many different output formats, each with a completely different appearance and even a different arrangement of content elements.

[edit] Simplified DocBook

DocBook offers a large number of features that may be overwhelming to a new user. For those who want the convenience of DocBook without a large learning curve, Simplified DocBook was designed. It is a small subset of DocBook designed for single documents such as articles or white papers (i.e., "books" are not supported). The Simplified DocBook DTD is currently at version 1.1. [1]

[edit] References

[edit] See also

[edit] External links

[edit] Tutorials and references

Retrieved from "http://en.wikipedia.org../../../d/o/c/DocBook_4a82.html"