tagging.txt

Tips regarding DocBook XML tagging
==================================

To get entries in the Index at the back, add entries like this in the
docbook source:

  <indexterm><primary>ABC</primary></indexterm>

This will result in the entry ABC showing up in the Index, with a
reference to the page where it is mentioned.

To get two levels in the index at the back, add entries like this to
the docbook source:

  <indexterm>
  <primary>artists</primary>
  <secondary>publicity rights on images of</secondary>
  </indexterm>

To index a range of paragrams/pages:

  <indexterm id="idxexchap" class='startofrange'>
    <primary>Example Chapter</primary></indexterm>
  ...
  <indexterm startref="idxexchap" class="endofrange"/>

Docbook howtos
--------------

http://developer.gnome.org/gdp-handbook/stable/docbook.html.en
http://www.docbook.org/tdg/en/html/docbook.html
http://www.docbook.org/tdg/en/html/indexterm.html

Docbook processing
------------------

xmlto with fop backend

 - showing norwegian language for system templates.

 - Overlap footnote and text body in some cases (BTS #683197)

 - incorrect index (missing page numbers for some, create wrong page
   number for some).

 - missing images (possibly BTS #567122)

xmlto with default backend

 - fail to process the docbook source (possibly BTW #683163)

dblatex

 - do not end a <part> when it should, gluing following chapters as if
   they belonged to the last <part> (BTS #683166).

 - Incorrect hyphens for multipage index references when using xetex
   (BTS #682901).

 - not showing norwegian language for system templates (BTS #682936).

docbook-xsl (aka xsltproc + fop)

 - both version 1.75.2+dfsg-5 (squeeze) and version 1.76.1+dfsg-1
   (wheezy) give broken footnotes and index.

Some ideas for docbook proposed processors:

  XMLMind (editor with PDF export support)
  Oxygen (editor with PDF export support)
  publican


Interesting links

  http://wepod.wordpress.com/lulu-specs/
  http://left.subtree.org/2011/04/09/wordpress-blog-to-print-book-a-case-study/

Good source of indexterm locations:

  http://www.jus.uio.no/sisu/src/free_culture.lawrence_lessig.sst