For the last three years, my daytime hours have mostly involved wrapping text in DocBook XML. A question is often asked of me is what tag should be used for a specific thing. Usually the thing in question is an inline element like a class name, a method name, or a GUI component of some sort. People get paralysed by indecision. They want to pick the right tag, and are presented with the tyranny of choice.

My answer to this sort of question is usually “Who cares? Keep writing. It doesn’t matter.” And for the vast majority of inline elements it really doesn’t matter. It is the block elements that define the structure of the document that really matter.

If you have written your content well then you shouldn’t need to put a class name in a <classname> tag for your readers to realise that it is a class name. The context of your writing should do that. Your DocBook system might do special markup for them, it might not, but the thing to remember is that your text should be capable of standing on its own.

Of course you may have a document build and publishing system that makes use of certain tags in special ways, like building indexes of specific tag references. In that case you probably have a style guide or other documentation that indicates what you need to do there.

So for people coming to DocBook for the first time, here is my list of tags that you need to know to get by and get your stuff written. Remember that it is your text within the tags that really matter. More content, less tags.

Tags that define your document overall:

  • <book> & <article>
  • <book_info> & <article_info>
  • <chapter>
  • <section>

Tags that define the structure of your writing:

  • <para>
  • <orderedlist>
  • <itemizedlist>
  • <listitem>
  • <variablelist>
  • <varlistentry>
  • <programlisting>
  • <screen>
  • <example>
  • <figure> & <mediaobject>
  • <table> & associated child tags
  • <note>
  • <important>
  • <warning>

Inline tags:

  • <code>
  • <filename>
  • <literal>
  • <xref>
  • <ulink>
  • <replaceable>
  • <emphasis>

Special stuff you should be aware of:

<xi:include> is not actually part of DocBook, it’s an XML extension that allows an XML file to reference other files (XML or otherwise). This is super handy because it lets you break your document down into multiple files, e.g. one per chapter.

Entities are another general XML construct that is very useful in DocBook. They actually cover three different things in XML but the most common use is as a mechanism to define a piece of content and assign it a name so you can reuse it within your document by simply using the name (with a special syntax). Using entities for anything that could get translated is generally frowned upon because it often causes problems. But for things that that get repeated often through a document and don’t get translated, like a company name, it can be really convenient. Entities are also the way you can use characters in your documents that have special meanings in XML, like the characters <, >, ', ", and &. You can also use entities to reference external files in a similar manner to <xi:include> but I recommend the use of <xi:include> instead.

CDATA or character data is a way to literally include content without it being parsed as XML. Handy for when you need to include samples of programming code or XML within your document.

References:

Docbook: The Definitive Guide.

If you work in DocBook you will need to spend time here, especially the DocBook Element Reference.

http://docbook.org/tdg/en/html/docbook.html

The Publican User Guide.

Publican is a great DocBook publishing tool. It strives to enforce good practices and the user guide contains some excellent advice.

http://jfearn.fedorapeople.org/en-US/Publican/2.7/html/Users_Guide/index.html

The Pressgang Jboss Documentation Guide.

Also contains good DocBook material especially for authors working with Docbook within a Maven build.

https://hudson.jboss.org/jenkins/job/JBoss_Documentation_Guide/lastSuccessfulBuild/artifact/trunk/target/docbook/publish/en-US/html/index.html