DocBook

DocBook is an application of the SGML/XML standard and includes its own DTD that is used more prominently in the area of technical documentation, especially to document all types of material and computer programs. There is an OASIS DocBook Technical Committee (originally SGML Open) that maintains and updates this standard. DocBook initially started as an SGML DTD, but as of version 4 there is an equivalent for XML.

As a semantic language, DocBook allows us to create documents in a neutral format, independent of presentation. In this neutral format, both the content and its logical structure are collected, thus allowing it to be published (presented) automatically in a multitude of formats: HTML, XHTML, EPUB, PDF, HTML Help man pages, etc., simply by applying & #34;templates" presentation, without requiring any changes to the original document.

Introduction

DocBook is an XML language. In its current version (5.0), it is formally defined by a RELAX NG schema with built-in Schematron rules. (An XML Schema+Schematron and a DTD also exist, but these are currently considered non-standard.)

DocBook documents do not describe the appearance or presentation of their contents, but only the meaning of said contents. For example, instead of indicating exactly how a certain phrase that is a chapter title should be displayed, DocBook simply indicates that the phrase is a chapter title. Subsequently, deciding where and how the title is to be displayed within the page will be the task of an external processing tool or the viewer application that we are managing.

DocBook has a large number of tags to describe semantic elements, including these in three main categories: structural, block and line.

The structural tags specify general characteristics of your contents. For example, the book element specifies that its child elements will be parts of a book: titles, chapters, glossaries, appendices, etc. Some structural tags are:

• set:
• book:
• part:
• article:
• chapter:
• appendix:
• dedication:

Structural elements can contain other structural elements, but they must always be first-level elements within a DocBook document.

The block tags represent elements such as paragraphs, lists, etc., and not all of them need to contain text in their content. inside. These block elements are usually distributed sequentially, and will be displayed one "below" of other. (Although "below" can vary depending on culture: in most Western languages "below" will mean a downward direction on the page; but in some Eastern languages, "below& #34; will mean a sense in columns from right to left. The DocBook specification is completely neutral to such concepts intrinsic to each culture.)

The line tags represent elements such as emphasized letters, hyper-links, etc, and are often applied to portions of text in inside a block element, usually causing the presentation processor tool to apply some kind of special typographical treatment to those portions. (The DocBook specification indicates that special typographic treatment is expected, but does not indicate exactly what specific treatment should be applied. For example, "emphasized letters" does not necessarily imply "italic letters"; the presentation tool can choose to increase their font size or change their background color.)

Examples

Article in SGML/XML DocBook

?xml version="1.0" standalone="no"? DOCTYPE article PUBLIC "-/OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" ▪ Lang="is"▪ ▪Creating Technical Documentation
DocBook▪ ≤2 ▪ ≤2LeonardoΔ/firstname ≤3KnightΔ/surname ◊ ◊ ▪ id="art-intro"▪ ▪Introduction▪ ≤2DocBook is a standard application
SGML/XML and includes its own DTD and is used in a way
the area of documentation
especially to document all types of
equipment and software for increased
information consult here ¢Ü url="http://www.oasis-open.org/docbook/"/ 2005.Δ/para ◊ ◊

From a semantic point of view, this document is an "article" (article), with its respective "title" (title). The "author" (author), and other "information" additional (articleinfo). This sample article consists of a single "section", also with its respective "title"; and with "paragraphs" (paragraph) of text.

Book in SGML/XML DocBook

 ?xml version="1.0" standalone="no"? DOCTYPE book PUBLIC "-/OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" ” Lang="is" id="simple_book"▪ ▪A very simple book▪ ¢Ü id="Chapter_1"▪ ▪Chapter 1▪ ≤2Hello world!Δ/para ≤2I hope your day is good!Δ/para Δ/chapter ¢Ü id="Chapter_2"▪ ▪Chapter 2▪ ≤2Hello again, world!Δ/para Δ/chapter Δ/book

From a semantic point of view, this document is a "book" (book), with a "title" (title); consists of two "chapters" (chapter), each with its own "title", and these "chapters" have "paragraphs" (paragraph) of text. All expressed in a format easily understandable by humans.

Schemes and validation

Both the different elements that make up a DocBook, as well as the rules for combining them (for example, that every "book" element must contain a "title" element, prior to any other structural element such as "chapter"), are formally defined in a schema, in such a way that computer programs can validate the document against said schema, and thus determine, at all times, if the document it is well-formed.

Writing

As XML documents, DocBook documents can be written with any text editor, although it will always be easier to write them with an XML editor, or better yet, with an XML editor that has DocBook-specific schemas built in. For example Emacs, working in nXML mode, or XML Copy Editor.

There are also more "visual" (WYSIWYG), such as XMLmind Editor ("XXE"), Oxygen XML Editor, capable of rendering DocBook documents by formatting them with CSS; or Syntext Serna, which performs XSL transformations in real time.

Post Processing

Furthermore, as XML documents, DocBook documents can be automatically validated and processed by any tool or programming language that supports XML.

These tools are often used to create output documents in a wide range of formats, often using "style sheets" DocBook XLS, a type of XSLT sheets that allow us to transform DocBook documents to other formats such as HTML, PDF, etc., allowing conversions so sophisticated as to include the automatic generation of tables of contents, glossaries and/or indexes, or that even allow previous content filtering, extracting only certain parts of the original DocBook.

Uses

DocBook is widely used in a few contexts, including the Linux Documentation Project, GNOME and GTK+ API references, and Linux kernel documentation. Solaris Operating Environment man pages are also generated from documents that use the DocBook DTDs or schemas.

History

DocBook was born in 1991, from a joint venture between HAL Computer Systems and O'Reilly & Associates, later evolving into its own organization (the Davenport Group), to end up, in 1998, being managed by the SGML Open consortium, which would later become the OASIS organization, within which there is currently the DocBook Technical Committee, in charge of maintaining the DocBook standard.

The DocBook specification is available in both SGML and XML formats, being defined by both a DTD document and a RELAX NG - W3C XML Schema. As of version 5, the RELAX NG scheme is the "normative" scheme, the rest of the formats being mere adaptations of it.

DocBook was born as an SGML application, but now its XML adaptation has replaced it in most uses. (Starting with version 4 of the SGML DTD, the XML DTD version has gone its own way and its own numbering scheme.)

In the beginning, the use of the DocBook format was practically limited to the group of companies participating in its design, but now it has been widely adopted by the entire free software community and by a wide spectrum of companies, existing in the market multitude of tools that make use of it.

Norman Walsh and the DocBook Open Repository development team maintain a set of DSSSL and XSL style sheets for generating PDF and HTML versions of DocBook documents (as well as developing other formats, including man and HTML help). Walsh is also the lead author of DocBook: The Definitive Guide, the official DocBook documentation. This book can be obtained under the GFDL license or in its printed version (ISBN 1565925807), published by O'Reilly & Associates."