Why Use a Bookmap

Using a plain DITA map, the transformation will produce a publication with a front page, a table of contents, chapters with content, and an index at the end. This is appropriate for most cases, but there are some use cases where some adjustments are necessary. For example, if you want to do one of the following:

• Remove the TOC or index.
• Add a glossary.
• Change the position of the TOC or the index relative to the sibling topics.
• Add a preface, frontmatter, or backmatter with copyright notices, abstracts, list of tables, list of figures, etc.

All of these can be achieved using a DITA <bookmap> element.

A bookmap has a more elaborate structure than a regular map. You should start by defining the title structure, with a main title and alternative title:

<!DOCTYPE bookmap PUBLIC "-//OASIS//DTD DITA BookMap//EN"  "bookmap.dtd">
<bookmap id="taskbook">
  <booktitle>
    <mainbooktitle>Publication Title</mainbooktitle>
    <booktitlealt>A very short description of the publication</booktitlealt>
  </booktitle>

Then you may define a frontmatter. For this, you can link the topics that need to appear before the main content. You can also define the location where the table of contents will be placed. In the example below, it appears between the abstract.dita and foreword.dita topics:

  <frontmatter>
    <topicref href="topics/abstract.dita"/>
    <booklists>
      <toc/>
    </booklists>
    <topicref href="topics/foreword.dita"/>
  </frontmatter>

Next, the topics are grouped into chapters:

  ...
  <chapter href="topics/installation.dita" />
  ...

At the end, you could define the structure of the backmatter. Just like for the frontmatter, you can include some topics and some generated content (such as the index). In the example below, the glossary is defined to come after the index, followed by a list of figures, and a list of tables. At the very end, there is a topic with some thank you notes:

  <backmatter>
    <topicref href="topics/conclusion.dita"/>
    <booklists>
      <indexlist/>

      <glossarylist>
        <topicref href="topics/xp.dita" keys="xp" print="yes" />
        <topicref href="topics/anti_lock_braking_system.dita" keys="abs" print="yes" />
      </glossarylist>

      <figurelist/>
      <tablelist/>     
    </booklists>
    <topicref href="topics/thanks.dita"/>
  </backmatter>