4.1 Introduction to DocBook

DocBook contains a large number of XML elements from which we only use a subset.

Be aware that XML (not just DocBook XML) has two special characters that cannot be used literally in text: < (the opening angle bracket) and & (the ampersand sign). Whenever you need to use those two characters literally, you have to use entities, like in this example: <literal> & <programlisting>.

Alternatively, you can wrap any content that contains characters that cannot be used literally within CDATA containers, like this:

<![CDATA[(content that might contain characters illegal in XML)]]>

This makes sense particularly for larger pieces of code within <programlisting> or similar containers.

We structure documentation using nested section elements. A book as DocBook defines it would look like this:

<book>
 <chapter>
  <section>
   <section>
    ...
   </section>
  </section>
 </chapter>
 <appendix>
  <section>
   ...
  </section>
 </appendix>
</book>