Red Hat Bugzilla – Bug 888371
Index in PDF doc has no sub-entries for each letter
Last modified: 2013-04-16 21:07:37 EDT
Created attachment 665553 [details]
Shows index produced using jade.
Description of problem:
The index in a PDF doc that is heavily cross-indexed has no sub-indexes by letter. This makes the index very hard to use. In the previous system we used to build our docs, the index could be expanded and there was a heading for each letter. This allowed the reader to go directly to, for instance, the K entries.
Without the letter sub-headings, the user has to page through dozens of pages trying to find something like "killActive." In a 36 page index, this can be frustrating.
Version-Release number of selected component (if applicable):
Steps to Reproduce:
I'm attaching to images showing the Publican produced index and a previous version of the doc with the index produced by jade.
Created attachment 665554 [details]
Shows index produced by Publican
Hi Mark, are you using wkhtmltopdf or FOP to generate the PDF?
I don't know for sure, but I think FOP.
I just download 2.8 and installed it, I believe from a rpm package, but I don't remember for sure. However I know I didn't build it from source.
So, whatever was set up from the install is what I'm using. One of the other developers on our project set up a brand, but it only has minor changes.
How could I check if the build is using FOP or whhtmltopdf?
wkhtmltopdf isn't available in any Fedora repos, so you'd have had to manually install it, which sounds unlikely.
To be sure you can run:
$ which wkhtmltopdf
If it's not found it's not being used.
I'm pretty sure I didn't install it, unless it was installed as part of the doc build tools I was using before we switched to Publican.
I'll double check tonight when I can get back to the system I use to build the docs.
I think I remember seeing a comment somewhere that if wkhtmotopdf was installed, then Publican detected it and used it?
(In reply to comment #5)
> I think I remember seeing a comment somewhere that if wkhtmotopdf was
> installed, then Publican detected it and used it?
This is correct, but I'm starting to think we should make that a config option so people can install a bunch of tools and pick the one they want to use.
Okay, I just checked on the Fedora system I use to build our docs. There is no wkhtmltopdf on it.
When you say "index" do you mean the index itself at the back of the book, or the index in the viewer (usually shown on the right hand side of the viewer)?
AIUI the "index" in the viewer is actually the table of contents.
I'm taking about the entry for the index in the viewer. If you look at the two .pgn files I attached:
The one that shows the PDF doc produced with jade, shows the last entry in the viewer, labeled "index" has an expand button. When expanded, there is a label for each letter that links to that part of the index in the back of the book. So, from the viewer, the reader can go directly to a subsection of the index. The reader can for instance go directly to the 'M's.
In the snapshot from the doc produced with Publican, the 'index' entry in the viewer is flat, can not be expanded. When the reader clicks on it, it goes directly to the start of the index. Then to find something in the 'M's, the reader needs to page down until she reaches the 'M's.
What I would like, and actually I'm speaking for several of our users that have complained about this, is to get the "index" entry in the viewer like the one we had with our previous build system. Where the "index" entry in the view can be expanded to show links to each letter subsection in the index.
I don't know exactly what in the tool chain that used jade for part of the processing achieved this.
AIUI that "index" is actually a list of bookmarks and the DocBook FO output does not put bookmarks inside the index.
To get a list of where bookmarks are placed and what they look like you can run:
$ grep bookmark /usr/share/sgml/docbook/xsl-stylesheets-1.77.1/fo/*
I think you'd need to override '<xsl:template match="indexterm" mode="index-symbol-div">' or '<xsl:template match="indexterm" mode="index-primary">' from autoidx.xsl to make one of them output an fo:bookmark.
FWIW wkhtmltopdf does what you want, but it's also a bit rough around the edges in other areas.