Take the 2-minute tour ×
Writers Stack Exchange is a question and answer site for authors, editors, reviewers, professional writers, and aspiring writers. It's 100% free, no registration required.

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.

share|improve this question
5  
an outstanding question! –  Lauren Ipsum Mar 2 '12 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). :( –  Neil Fein Mar 5 '12 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? –  Monica Cellio Mar 5 '12 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? –  Neil Fein Mar 5 '12 at 4:45
    
Actually I would propose that this go to Programmers. –  Joshua Drake Apr 10 '12 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.

share|improve this answer
    
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. –  Monica Cellio May 27 '13 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.

share|improve this answer
    
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. –  Monica Cellio May 28 '13 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 Aug 27 '13 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.) –  Monica Cellio Aug 27 '13 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 Aug 27 '13 at 14:02

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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