Editing DocBook (section)

== Design ==
DocBook is an [[XML]] language. In its current version (5.x), DocBook's language is formally defined by a [[RELAX NG]] [[XML schema|schema]] 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 (summary)|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 <code>book</code> 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:

* ''<code>set</code>:'' Titled collection of one or more <code>book</code>s or <code>article</code>s, can be nested with other sets
* ''<code>book</code>:'' Titled collection of <code>chapter</code>s, <code>article</code>s, and/or <code>part</code>s, with optional glossaries, appendices, etc.
* ''<code>part</code>:'' Titled collection of one or more <code>chapter</code>s—can be nested with other parts, and may have special introductory text
* ''<code>article</code>:'' Titled, unnumbered collection of block-level elements
* ''<code>chapter</code>:'' 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
* ''<code>appendix</code>:'' Contains text that represents an [[Addendum|appendix]]
* ''<code>dedication</code>:'' 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 system#Directionality|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 <code>emphasis</code> 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 ===

<syntaxhighlight lang="xml">
 <?xml version="1.0" encoding="UTF-8"?>
 <book xml:id="simple_book" xmlns="http://docbook.org/ns/docbook" version="5.0">
   <title>Very simple book</title>
   <chapter xml:id="chapter_1">
     <title>Chapter 1</title>
     <para>Hello world!</para>
     <para>I hope that your day is proceeding <emphasis>splendidly</emphasis>!</para>
   </chapter>
   <chapter xml:id="chapter_2">
     <title>Chapter 2</title>
     <para>Hello again, world!</para>
   </chapter>
 </book>
</syntaxhighlight>

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 <code>book</code>. 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 <code>id</code> attributes in the example.)

A <code>book</code> element must contain a <code>title</code>, or an <code>info</code> element containing a <code>title</code>. This must be before any child structural elements. Following the title are the structural children, in this case, two <code>chapter</code> elements. Each of these must have a <code>title</code>. They contain <code>para</code> block elements, which can contain free text and other inline elements like the <code>emphasis</code> in the second paragraph of the first chapter.

=== Schemas and validation ===

Rules are formally defined in the DocBook [[XML schema]]. 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.