Suggestion: GenPDFAddOn should format recursive topics so the TOC shows the hierarchy

Hi guys,

Thanks for the possibility to recursively render wiki topics to PDF, we really needed it.

But when looking on the generated TOC, all the topic names remain on the same level, i.e. they're not shifted according to the deepness in the hierarchy. It would be good to have such a nice looking TOC.

Unfortunately I do not know Perl and Foswiki enough, so when looking into GenPDF.pm I've just noticed that maybe we could have lists of different levels topics after _depthFirst call. And maybe then it could be used to correct topic header during rendering instead of incrementing shift for all topics.

What would you say about such enhancement? Looking forward to hearing from you

-- AndreyStoliarov - 11 Dec 2009

---

I suspect that this would be a pretty complex enhancement. The PDF TOC is generated from the html headings <h1> <h2> ... <h6> which are generated from Foswiki TML headings (---++...). We would have to either find all TML and HTML headings in the un-rendered markup and increment them depending upon the depth of the topic, or find/increment the html headings in the rendered TML. And since the hierarchy of topics can be deep, we need to figure out how to handle headings when the maximum depth is exceeded. HTML defines only 6 levels of headings, so we would become limited fairly quickly. I do like the idea, but I'm not sure about the implementation.

-- GeorgeClark - 11 Dec 2009

>The PDF TOC is generated from the html headings <h1> <h2> ... <h6> which are generated from Foswiki TML headings (---++...)

What about topic names themselves which are not part of the topic content but appears in pdf at the very beginning of every topic first page? Are they generated by wiki renderer too? If so and if they're by default rendered as <h1>, then we can search topic names surrounded by those tags and maybe followed by a line break.

-- AndreyStoliarov - 11 Dec 2009

From what I can see, the generated <h1> headings are only inserted if the topic does not contain an <h1> heading. htmldoc supports up to header level 15 even though HTML only supports 6, and the genpdf routine can shift the headers by the amount specified in GENPDFADDON_HEADERSHIFT I'll look at the code a bit and see if I could set an automatic header shift. So for recursive rendering, setting HEADERSHIFT to "auto" would result in a header shift equal to the depth of the document. If it appears that i can get something working, I'll open a task and make the changes.

I have some test code working, but htmldoc does not do what you want. The way the plugin works, is that each page processed recursively is rendered as a separate, complete html file. When generating a PDF, there are 3 modes. --book, --webpage and --continuous. In book mode, each input file is considered a "Chapter" and gets an automatic chapter heading in the PDF. The other modes generate a PDF without Table of Contents or Title page. --continuous mode eliminates page breaks as well. So even though I've generated html files starting with <h2>, it still gets a "Chapter Heading" or <h1> level header in the TOC. It doesn't look like this can be accomplished without major changes.

-- GeorgeClark - 12 Dec 2009

I've been doing some more work on GenPDFAddOn and discovered that the print cover used by GenPDF is for some unexplained reason inserting an empty heading 1 <h1></h1> at the beginning of each topic. This caused htmldoc to always expand the recursive topics as a new chapter. I've removed the empty headings and the header shifting for child topics is now generating the requested behavior.

Each "H1" heading generates a new PDF chapter. The auto-shift will shift the headers by the "depth" of the topic in the recursion.

I'll include this feature in the next release of the plugin, including an example topic that demonstrates the feature.

-- GeorgeClark - 07 Jan 2010

Task filed - Tasks.Item2604

A test version that includes this feature is posted at GenPDFAddOn.

-- GeorgeClark - 10 Jan 2010