tagging.txt

   1 Tips regarding DocBook XML tagging
   2 ==================================
   3
   4 To get entries in the Index at the back, add entries like this in the
   5 docbook source:
   6
   7   <indexterm><primary>ABC</primary></indexterm>
   8
   9 This will result in the entry ABC showing up in the Index, with a
  10 reference to the page where it is mentioned.
  11
  12 To get two levels in the index at the back, add entries like this to
  13 the docbook source:
  14
  15   <indexterm>
  16   <primary>artists</primary>
  17   <secondary>publicity rights on images of</secondary>
  18   </indexterm>
  19
  20 To index a range of paragrams/pages:
  21
  22   <indexterm id="idxexchap" class='startofrange'>
  23     <primary>Example Chapter</primary></indexterm>
  24   ...
  25   <indexterm startref="idxexchap" class="endofrange"/>
  26
  27 Docbook howtos
  28 --------------
  29
  30 http://developer.gnome.org/gdp-handbook/stable/docbook.html.en
  31 http://www.docbook.org/tdg/en/html/docbook.html
  32 http://www.docbook.org/tdg/en/html/indexterm.html
  33
  34 Docbook processing
  35 ------------------
  36
  37 xmlto with fop backend
  38
  39  - showing norwegian language for system templates.
  40
  41  - Overlap footnote and text body in some cases (BTS #683197)
  42
  43  - incorrect index (missing page numbers for some, create wrong page
  44    number for some).
  45
  46  - missing images (possibly BTS #567122)
  47
  48 xmlto with default backend
  49
  50  - fail to process the docbook source (possibly BTW #683163)
  51
  52 dblatex
  53
  54  - do not end a <part> when it should, gluing following chapters as if
  55    they belonged to the last <part> (BTS #683166).
  56
  57  - Incorrect hyphens for multipage index references when using xetex
  58    (BTS #682901).
  59
  60  - not showing norwegian language for system templates (BTS #682936).
  61
  62 docbook-xsl (aka xsltproc + fop)
  63
  64  - both version 1.75.2+dfsg-5 (squeeze) and version 1.76.1+dfsg-1
  65    (wheezy) give broken footnotes and index.
  66
  67 Some ideas for docbook proposed processors:
  68
  69   XMLMind (editor with PDF export support)
  70   Oxygen (editor with PDF export support)
  71   publican
  72
  73
  74 Interesting links
  75
  76   http://wepod.wordpress.com/lulu-specs/
  77   http://left.subtree.org/2011/04/09/wordpress-blog-to-print-book-a-case-study/
  78
  79 Good source of indexterm locations:
  80
  81   http://www.jus.uio.no/sisu/src/free_culture.lawrence_lessig.sst