DocBook
   HOME

TheInfoList



OR:

DocBook is a
semantic Semantics is the study of linguistic Meaning (philosophy), meaning. It examines what meaning is, how words get their meaning, and how the meaning of a complex expression depends on its parts. Part of this process involves the distinction betwee ...
markup language A markup language is a Encoding, text-encoding system which specifies the structure and formatting of a document and potentially the relationships among its parts. Markup can control the display of a document or enrich its content to facilitate au ...
for technical
documentation Documentation is any communicable material that is used to describe, explain or instruct regarding some attributes of an object, system or procedure, such as its parts, assembly, installation, maintenance, and use. As a form of knowledge managem ...
. It was originally intended for writing technical documents related to computer hardware and software, but it can be used for any other sort of documentation. As a semantic language, DocBook 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 Hypertext Markup Language (HTML) is the standard markup language for documents designed to be displayed in a web browser. It defines the content and structure of web content. It is often assisted by technologies such as Cascading Style Sheets ( ...
,
XHTML Extensible HyperText Markup Language (XHTML) is part of the family of XML markup languages which mirrors or extends versions of the widely used HyperText Markup Language (HTML), the language in which Web pages are formulated. While HTML, pr ...
,
EPUB EPUB is an e-book file format that uses the ".epub" file extension. The term is short for ''electronic publication'' and is sometimes stylized as ''ePUB''. EPUB is supported by many e-readers, and compatible software is available for most smart ...
,
PDF Portable document format (PDF), standardized as ISO 32000, is a file format developed by Adobe Inc., Adobe in 1992 to present documents, including text formatting and images, in a manner independent of application software, computer hardware, ...
, man pages, WebHelpDocBook WebHelp Project
/ref> and HTML Help, without requiring users to make any changes to the source. In other words, when a document is written in DocBook format it becomes easily portable into other formats, rather than needing to be rewritten.


Design

DocBook is an
XML Extensible Markup Language (XML) is a markup language and file format for storing, transmitting, and reconstructing data. It defines a set of rules for encoding electronic document, documents in a format that is both human-readable and Machine-r ...
language. In its current version (5.x), DocBook's language is formally defined by a RELAX NG
schema Schema may refer to: Science and technology * SCHEMA (bioinformatics), an algorithm used in protein engineering * Schema (genetic algorithms), a set of programs or bit strings that have some genotypic similarity * Schema.org, a web markup vocab ...
with integrated Schematron rules. (There are also W3C XML Schema+Schematron and Document Type Definition (DTD) versions of the schema available, but these are considered non-standard.) As a semantic language, DocBook documents do not describe what their contents "look like", but rather the meaning of those contents. For example, rather than explaining how the abstract for an article might be visually formatted, DocBook simply says that a particular section ''is'' an abstract. It is up to an external processing tool or application to decide where on a page the abstract should go and what it should look like or whether or not it should be included in the final output at all. DocBook provides a vast number of semantic element tags. They are divided into three broad categories, namely structural, block-level, and inline. ''Structural'' tags specify broad characteristics of their contents. The book element, for example, specifies that its child elements represent the parts of a book. This includes a title, chapters, glossaries, appendices, and so on. DocBook's structural tags include, but are not limited to: * ''set:'' Titled collection of one or more books or articles, can be nested with other sets * ''book:'' Titled collection of chapters, articles, and/or parts, with optional glossaries, appendices, etc. * ''part:'' Titled collection of one or more chapters—can be nested with other parts, and may have special introductory text * ''article:'' Titled, unnumbered collection of block-level elements * ''chapter:'' Titled, numbered collection of block-level elements—chapters don't require explicit numbers, a chapter number is the number of previous chapter elements in the XML document plus 1 * ''appendix:'' Contains text that represents an appendix * ''dedication:'' Text represents the dedication of the contained structural element Structural elements can contain other structural elements. Structural elements are the only permitted top-level elements in a DocBook document. ''Block-level'' tags are elements like paragraph, lists, etc. Not all these elements can directly contain text. Sequential block-level elements render one "after" another. After, in this case, can differ depending on the language. In most Western languages, "after" means below: text paragraphs are printed down the page. Other languages' writing systems can have different directionality; for example, in Japanese, paragraphs are often printed in downward columns, with the columns running from right to left, so "after" in that case would be to the left. DocBook semantics are entirely neutral to these kinds of language-based concepts. ''Inline-level'' tags are elements like emphasis, hyperlinks, etc. They wrap text within a block-level element. These elements do not cause the text to break when rendered in a paragraph format, but typically they cause the document processor to apply some kind of distinct typographical treatment to the enclosed text, by changing the font, size, or similar attributes. (The DocBook specification ''does'' say that it expects different typographical treatment, but it does not offer specific requirements as to what this treatment may be.) That is, a DocBook processor doesn't have to transform an emphasis tag into ''italics''. A reader-based DocBook processor could increase the size of the words, or, a text-based processor could use bold instead of italics.


Sample document

Very simple book Chapter 1 Hello world! I hope that your day is proceeding splendidly! Chapter 2 Hello again, world! Semantically, this document is a "book", with a "title", that contains two "chapters" each with their own "titles". Those "chapters" contain "paragraphs" that have text in them. The markup is fairly readable in English. In more detail, the root element of the document is book. All DocBook elements are in an XML Namespace, so the root element has an ''xmlns'' attribute to set the current namespace. Also, the root element of a DocBook document must have a ''version'' that specifies the version of the format that the document is built on. (XML documents can include elements from multiple namespaces at once, like the id attributes in the example.) A book element must contain a title, or an info element containing a title. This must be before any child structural elements. Following the title are the structural children, in this case, two chapter elements. Each of these must have a title. They contain para block elements, which can contain free text and other inline elements like the emphasis in the second paragraph of the first chapter.


Schemas and validation

Rules are formally defined in the DocBook
XML schema An XML schema is a description of a type of XML document, typically expressed in terms of constraints on the structure and content of documents of that type, above and beyond the basic syntactical constraints imposed by XML itself. These constrai ...
. Appropriate programming tools can validate an XML document (DocBook or otherwise), against its corresponding schema, to determine if (and where) the document fails to conform to that schema. XML editing tools can also use schema information to avoid creating non-conforming documents in the first place.


Authoring and processing

Because DocBook is XML, documents can be created and edited with any text editor. A dedicated XML editor is likewise a functional DocBook editor. DocBook provides schema files for popular XML schema languages, so any XML editor that can provide content completion based on a schema can do so for DocBook. Many graphical or WYSIWYG
XML editors Extensible Markup Language (XML) is a markup language and file format for storing, transmitting, and reconstructing data. It defines a set of rules for encoding documents in a format that is both human-readable and machine-readable. The World ...
come with the ability to edit DocBook like a
word processor A word processor (WP) is a device or computer program that provides for input, editing, formatting, and output of text, often with some additional features. Early word processors were stand-alone devices dedicated to the function, but current word ...
. Tables, list items, and other stylized content can be copied and pasted into the DocBook editor and will be preserved in the DocBook XML output. Because DocBook conforms to a well-defined XML schema, documents can be validated and processed using any tool or programming language that includes XML support.


History

DocBook began in 1991 in discussion groups on
Usenet Usenet (), a portmanteau of User's Network, is a worldwide distributed discussion system available on computers. It was developed from the general-purpose UUCP, Unix-to-Unix Copy (UUCP) dial-up network architecture. Tom Truscott and Jim Elli ...
and eventually became 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 In ecology, an oasis (; : oases ) is a fertile area of a desert or semi-desert environmentSGML The Standard Generalized Markup Language (SGML; International Organization for Standardization, ISO 8879:1986) is a standard for defining generalized markup languages for documents. ISO 8879 Annex A.1 states that generalized markup is "based on t ...
and
XML Extensible Markup Language (XML) is a markup language and file format for storing, transmitting, and reconstructing data. It defines a set of rules for encoding electronic document, documents in a format that is both human-readable and Machine-r ...
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 The Standard Generalized Markup Language (SGML; International Organization for Standardization, ISO 8879:1986) is a standard for defining generalized markup languages for documents. ISO 8879 Annex A.1 states that generalized markup is "based on t ...
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 FreeBSD is a free-software Unix-like operating system descended from the Berkeley Software Distribution (BSD). The first version was released in 1993 developed from 386BSD, one of the first fully functional and free Unix clones on affordable ...
,
KDE KDE is an international free software community that develops free and open-source software. As a central development hub, it provides tools and resources that enable collaborative work on its projects. Its products include the KDE Plasma gra ...
, GNOME desktop documentation, the GTK+
API An application programming interface (API) is a connection between computers or between computer programs. It is a type of software interface, offering a service to other pieces of software. A document or standard that describes how to build ...
references, the
Linux kernel The Linux kernel is a Free and open-source software, free and open source Unix-like kernel (operating system), kernel that is used in many computer systems worldwide. The kernel was created by Linus Torvalds in 1991 and was soon adopted as the k ...
documentation (which, as of July 2016, is transitioning to
Sphinx A sphinx ( ; , ; or sphinges ) is a mythical creature with the head of a human, the body of a lion, and the wings of an eagle. In Culture of Greece, Greek tradition, the sphinx is a treacherous and merciless being with the head of a woman, th ...
/ reStructuredText), and the work of the Linux Documentation Project.


Pre DocBook v5.0

Until DocBook 5, DocBook was defined normatively by a Document Type Definition (DTD). Because DocBook was built originally as an application of
SGML The Standard Generalized Markup Language (SGML; International Organization for Standardization, ISO 8879:1986) is a standard for defining generalized markup languages for documents. ISO 8879 Annex A.1 states that generalized markup is "based on t ...
, the DTD was the only available schema language. DocBook 4.x formats can be SGML or XML, but the XML version does not have its own namespace. DocBook 4.x formats had to live within the restrictions of being defined by a DTD. The most significant restriction was that an element name uniquely defines its possible contents. That is, an element named info must contain the same information no matter where it is in the DocBook file. As such, there are many kinds of info elements in DocBook 4.x: bookinfo, chapterinfo, etc. Each has a slightly different content model, but they do share some of their content model. Additionally, they repeat context information. The book's info element is that, because it is a direct child of the book; it does not need to be named specially for a human reader. However, because the format was defined by a DTD, it did have to be named as such. The root element does not have or need a ''version'', as the version is built into the DTD declaration at the top of a pre-DocBook 5 document. DocBook 4.x documents are not compatible with DocBook 5, but can be converted into DocBook 5 documents via an XSLT stylesheet. One (db4-upgrade.xsl) is provided as part of the distribution of the DocBook 5 schema and specification package.


Output formats

DocBook files are used to prepare output files in a wide variety of formats. Nearly always, this is accomplished using DocBook XSL stylesheets. These are
XSLT XSLT (Extensible Stylesheet Language Transformations) is a language originally designed for transforming XML documents into other XML documents, or other formats such as HTML for web pages, plain text, or XSL Formatting Objects. These formats c ...
stylesheets that transform DocBook documents into a number of formats (
HTML Hypertext Markup Language (HTML) is the standard markup language for documents designed to be displayed in a web browser. It defines the content and structure of web content. It is often assisted by technologies such as Cascading Style Sheets ( ...
, XSL-FO for later conversion into
PDF Portable document format (PDF), standardized as ISO 32000, is a file format developed by Adobe Inc., Adobe in 1992 to present documents, including text formatting and images, in a manner independent of application software, computer hardware, ...
, etc.). These stylesheets can be sophisticated enough to generate tables of contents, glossaries, and indexes. They can oversee the selection of particular designated portions of a master document to produce different versions of the same document (such as a "tutorial" or a "quick-reference guide", where each of these consist of a subset of the material). Users can write their own customized stylesheets or even a full-fledged program to process the DocBook into an appropriate output format as their needs dictate. Norman Walsh and the DocBook Project development team maintain the key application for producing output from DocBook source documents: A set of
XSLT XSLT (Extensible Stylesheet Language Transformations) is a language originally designed for transforming XML documents into other XML documents, or other formats such as HTML for web pages, plain text, or XSL Formatting Objects. These formats c ...
stylesheets (as well as a legacy set of DSSSL stylesheets) that can generate high-quality
HTML Hypertext Markup Language (HTML) is the standard markup language for documents designed to be displayed in a web browser. It defines the content and structure of web content. It is often assisted by technologies such as Cascading Style Sheets ( ...
and print ( FO/
PDF Portable document format (PDF), standardized as ISO 32000, is a file format developed by Adobe Inc., Adobe in 1992 to present documents, including text formatting and images, in a manner independent of application software, computer hardware, ...
) output, as well as output in other formats, including RTF, man pages and HTML Help. Web help is a chunked HTML output format in the DocBook XSL stylesheets that was introduced in version 1.76.1. The documentation for web help also provides an example of web help and is part of the DocBook XSL distribution. The major features are its fully CSS-based page layout, search of the help content, and a table of contents in collapsible-tree form. Search has stemming, match highlighting, explicit page-scoring, and the standard multilingual tokenizer. The search and TOC are in a pane that appears as a frameset, but is actually implemented with div tags and cookies (so that it is progressive).


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 steep 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.


Criticism

Ingo Schwarze, the author of
OpenBSD OpenBSD is a security-focused operating system, security-focused, free software, Unix-like operating system based on the Berkeley Software Distribution (BSD). Theo de Raadt created OpenBSD in 1995 by fork (software development), forking NetBSD ...
's mandoc, considers DocBook inferior to the semantic ''mdoc'' macro for man pages. In an attempt to write a DocBook-to-mdoc converter (previous converters like docbook-to-man do not cover semantic elements), he finds the semantic parts "bloated, redundant, and incomplete at the same time" compared to elements covered in mdoc. Moreover, Schwarze finds the DocBook specification not specific enough about the use of tags, the language non-portable across versions, rough in details and overall inconsistent.


See also

*
List of document markup languages The following is a list of document markup languages. You may also find the List of markup languages of interest. Well-known document markup languages * HyperText Markup Language (HTML) – an ad hoc markup language that was originally created f ...
* Comparison of document markup languages * DocBook XSL *
Darwin Information Typing Architecture The Darwin Information Typing Architecture (DITA) specification defines a set of document types for authoring and organizing topic-oriented information, as well as a set of mechanisms for combining, extending, and constraining document types. It ...
* LinuxDoc *
LaTeX Latex is an emulsion (stable dispersion) of polymer microparticles in water. Latices are found in nature, but synthetic latices are common as well. In nature, latex is found as a wikt:milky, milky fluid, which is present in 10% of all floweri ...


References


Further reading

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


External links


DocBook.org
- Collection of DocBook information, including a 4.x and 5.0 version of ''DocBook: The Definitive Guide'' and all versions of the DocBook schemas/DTDs.
DocBook Repository at OASIS
- Normative home of DocBook schema/DTD.
DocBook XSL Project page
at SourceForge.net
XSLT 1.0 Stylesheets for DocBook
at
GitHub GitHub () is a Proprietary software, proprietary developer platform that allows developers to create, store, manage, and share their code. It uses Git to provide distributed version control and GitHub itself provides access control, bug trackin ...

DocBook Demystification HOWTO

DocBook: The Definitive Guide, 1st edition, v. 2.0.6
- Fully bookmarked PDF of the Guide for DocBook 3.x and 4.x.

{{Authority control Markup languages Document-centric XML-based standards Technical communication Technical communication tools Software documentation Open formats SGML