For our SDK, we generate individual documents (PDFs) and one big HTML doc set (CHM file) from the same Docbook source. Each book has an index, and the HTML version has an integrated index that is the union of all the individual entries.

We have been focusing on the individual books in crafting our index nouns and verbs. Sometimes combining them in the global index produces the right result -- if books A, B, and C all use verb1, verb2, noun1, etc in the same way, you generally want those to sort together.

Sometimes, however, the terms -- while meaningful in their original contexts -- do not play well in a global index. In a book about database integration "synchronization" might be a good index term (how to keep your app up to date with the DB), but "synchronization" means something different in a book about networking, and if you're trying to look up the former you don't want to be bothered with the latter. You could change those entries to "synchornization, database" and "synchronization, venue", which helps the global index, but they look kind of stupid in individual books that are all about databases or venues. Similarly, "rendering" means different things if you're talking about the low-level graphics layer (e.g. Swing) or a higher-level graphing system. (While I'm semi-making up these examples, yes a single SDK does cover topics this broad.)

What are some strategies for either (a) crafting index terms that work in both contexts or (b) varying how the local and global indexes are produced from a single source? For an example of the latter, is there some way that Docbook could support adding a word (context) to only the global version of an index entry?

We're using version 4.4 of the Docbook DTD, and we use XSLTProc, XEP (PDF), and HHC (CHM) to produce the documents. We drive the whole build using Ant targets.

  • 5
    an outstanding question! Commented Mar 2, 2012 at 11:08
  • Has anyone tried posting a link to this in the SO chatroom? This may in theory be the best place for this question, but the site doesn't have as many tech writers as we'd like (I wish we had more). :( Commented Mar 5, 2012 at 1:33
  • It hadn't occurred to me that there would be a tech-writing presence on SO. If there is, a link there sounds like a fine idea. Neil, are you active there? Commented Mar 5, 2012 at 3:53
  • No, alas. I know enough HTML and Javascript and CSS to get myself into trouble, but no actual programming. I really woud like to see more tech writers here, though, and it's important to me that this site be friendly to tech writing questions. If you have any thoughts about how to attract tech writers, ping me on chat? Commented Mar 5, 2012 at 4:45
  • Actually I would propose that this go to Software Engineering. Commented Apr 10, 2012 at 14:38

2 Answers 2


It might be worth employing the services of a professional indexer to create the index as a separate document, rather than generate the index from embedded codes. The types of difficulties that you have noted are familiar to indexers. An index written by an indexer is probably only applicable to a PDF though.

  • Do you mean manually create separate indexes for the individual books and for the whole set? That sounds like it would be hard to maintain over multiple releases. Commented May 27, 2013 at 1:12

LaTeX is a very typesetting powerful environment which provides ways of managing indexes. Have a look at The LaTeX project and TeX Stack Exchange.

  • How does LaTex fit into a tool chain that's currently based on DocBook XML? And how semantic is LaTeX these days? E.g. can you mark something as a class, function, XML element, etc and then associate formatting with that? Porting our large body of semantically-marked-up DocBook XML would be a major effort. Commented May 28, 2013 at 1:42
  • @MonicaCellio pandoc can convert a subset of DocBook XML to LaTeX, I don't know if that subset would be enough to be useful to you though. It can also generate PDF and HTML, but I don't know if it is able to generate indexes as you are describing.
    – evilsoup
    Commented Aug 27, 2013 at 10:44
  • Thanks @evilsoup. The core of my question is about the indexing, which requires either tools magic to manipulate the index contents or a change in (human) approach to creating the entries, maybe both. How it gets typeset seems tangential to me; if LaTeX doesn't have context-sensitive indexing then porting to it doesn't seem to help. (I should have asked that in my first comment, sorry.) Commented Aug 27, 2013 at 12:50
  • @MonicaCellio LaTeX probably can accomplish this, what I meant was that the pandoc program itself cannot. Unfortunately I don't know for sure -- I only use LaTeX on a very basic/superficial level. You might be well-served to ask a related question on tex.stackexchange.com ; this is the most likely candidate for a prepackaged solution, I think.
    – evilsoup
    Commented Aug 27, 2013 at 14:02

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.