Bug 888371

Summary: Index in PDF doc has no sub-entries for each letter
Product: [Community] Publican Reporter: Mark Miesfeld <miesfeld>
Component: publicanAssignee: Jeff Fearn <jfearn>
Status: CLOSED CURRENTRELEASE QA Contact: tools-bugs <tools-bugs>
Severity: unspecified Docs Contact:
Priority: unspecified    
Version: 2.8CC: rglasz, r.landmann, rlandman
Target Milestone: ---   
Target Release: ---   
Hardware: Unspecified   
OS: Unspecified   
Whiteboard:
Fixed In Version: Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: 2013-04-16 21:07:37 EDT Type: Bug
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Attachments:
Description Flags
Shows index produced using jade.
none
Shows index produced by Publican none

Description Mark Miesfeld 2012-12-18 10:07:13 EST
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):


How reproducible:


Steps to Reproduce:
1.
2.
3.
  
Actual results:


Expected results:


Additional info:

I'm attaching to images showing the Publican produced index and a previous version of the doc with the index produced by jade.
Comment 1 Mark Miesfeld 2012-12-18 10:08:27 EST
Created attachment 665554 [details]
Shows index produced by Publican
Comment 2 Jeff Fearn 2012-12-18 17:00:38 EST
Hi Mark, are you using wkhtmltopdf or FOP to generate the PDF?
Comment 3 Mark Miesfeld 2012-12-18 17:12:07 EST
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?
Comment 4 Jeff Fearn 2012-12-18 17:22:09 EST
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.
Comment 5 Mark Miesfeld 2012-12-18 17:31:17 EST
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?
Comment 6 Jeff Fearn 2012-12-18 17:47:30 EST
(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.
Comment 7 Mark Miesfeld 2012-12-18 22:03:45 EST
Okay, I just checked on the Fedora system I use to build our docs.  There is no wkhtmltopdf on it.
Comment 8 Jeff Fearn 2012-12-18 22:24:49 EST
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.
Comment 9 Mark Miesfeld 2012-12-18 22:42:05 EST
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.
Comment 10 Jeff Fearn 2012-12-18 23:10:56 EST
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.