Post History

Source: https://writers.stackexchange.com/q/5136
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

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.

Original score: 11