Better TOC control for PDF output

[John P]

Currently I have a Flare project with over 500 topics and I'm creating online and printed PDF output.

In my Flare TOC file, I have unlinked books that are used as chapter headings in printed output. In the PDF target, I enabled "Inject headings for unlinked books in TOC" and am also using CSS styling to control the heading level of each topic. I've accomplished this by creating classes for each heading level and assigning that to the h1 topic title, so there is h1.TOC1, h1.TOC2, h1.TOC3, etc. I have gone through each topic in my project and assigned the appropriate h1 class based on the heading level I want in the TOC.

The reason that I don't use the "Use TOC depth for heading levels" setting is that I don't like that Flare automatically changes the heading level of topics in the body of the printed output. So the title of a topic that is nested say three levels deep in the TOC gets changed to h3. (I am using the h1, h2, and h3 styles within my topics to denote headings and subheadings within the project, as is standard in many HTML outputs. Therefore, I don't want to have h1, h2, h3 etc. all look identical.)

There are several problems associated with this method:
- It was very labor intensive to manually style each topic's h1 heading according to the TOC heading level I wanted.
- There is no way that I know of to customize the look of a generated TOC, such as breaking it up by chapter. For instance:

Introduction
Getting started...1
Using settings....2
Logging in........3

Preferences
What are preferences...4
General preferences.....5

I'd like the ability to do the following:
1. With "Inject headings for unlinked books in the TOC" enabled, add the ability to set which element is used for the injected heading. Now it is hard coded to use h1 with no class. If this could be set to some other element, it would be easier to control it's style in the TOC, page breaks before, etc.

2. With "Use TOC depth for heading levels", it would be nice if that had an associated setting to only do this in the TOC itself, and not in the body. This was already mentioned here: http://forums.madcapsoftware.com/viewto ... 10&t=17359

I find the PDF Target very useful, as I now don't have to do the intermediate step of creating Word output and then publishing to PDF. However adding better / easier-to-use controls over how the PDF generated TOC looks would be a big improvement. An explanded Generated TOC section for PDF Targets would be great?

Thanks,
John

[LTinker68]

The reason that I don't use the "Use TOC depth for heading levels" setting is that I don't like that Flare automatically changes the heading level of topics in the body of the printed output. So the title of a topic that is nested say three levels deep in the TOC gets changed to h3. (I am using the h1, h2, and h3 styles within my topics to denote headings and subheadings within the project, as is standard in many HTML outputs. Therefore, I don't want to have h1, h2, h3 etc. all look identical.)

Sorry, I'm a little confused by this. When you say you don't want h1/h2/h3 to be identical, are you talking in the online output or the PDF output? Because you can style them differently between the two. So for online output you can have different font sizes/colors for all three, and for PDF output you can have them all set to be identical. Or the other way around, if you prefer.

Could you explain more what the problem is with using the "Use TOC depth" feature in your situation?

[John P]

What I'm getting at is that there is the ability to enable the "Use TOC depth for heading levels" setting, and then make h1, h2, h3, and h4 all identical to one another in the Print CSS. By doing this, you get an indented, tree-view Table of Contents (that follows the Flare TOC) in your printed output, and in the body, all the headers appear as though they are the same element (even though they're not).

So, assuming each topic starts with an h1 title, those titles are converted to h1, h2 h3 or h4 based on the TOC heading level. By styling them to be identical, you are simulating that they are the same element.

However, this is a workaround and it means that you cannot use h1, h2, h3, h4 for other purposes in your content. I use them for other purposes in my project.

What I am asking for is the ability to use the TOC depth in the Flare TOC (fltoc) and have that reflected in the print TOC WITHOUT having any of the h1 topic titles in the body changed automatically to h2, h3 etc.

[Nita Beck]

What I am asking for is the ability to use the TOC depth in the Flare TOC (fltoc) and have that reflected in the print TOC WITHOUT having any of the h1 topic titles in the body changed automatically to h2, h3 etc.

The whole objective of the Toc Depth feature is to have Flare swap in the right heading based on a TOC item's level within the TOC. So, no, I don't there is a way to use the TOC Depth feature to achieve something it was not designed to achieve. (Forgive me if my response seems snarky. I'm not being snarky, but rather completely serious.)

FWIW, I exclusively use only h1 and h2 for the first-level headings in my topics, which I output both to a Help system and to PDF guides. I reserve h1s for those topics that will be at the top level in the TOC, that is, those linked to top-level books. So for a Help system, these will be the first topics in their respective sections of the Help, and for a PDF guide, these will be the first topics in their respective chapters. I use h2 for all other topics' first headings. (I do use h3s within topics for subsections.) This scheme is very simple, so I never have to fuss with thinking about where some topic is going to be nested within a Help system. And by using the TOC Depth feature for my PDF guides, I let Flare do all the heavy lifting. I never have to think about whether I'm using the correct heading level. And I think this scheme best supports single-sourcing. I can invent new TOCs and can rearrange existing TOCs to my heart's content, and never have to worry about going back and changing how I've tagged the topics' headings.

[NorthEast]

John P, if I understand your scenario correctly, then I think you can achieve what you want without manual formatting, and by using the TOC-depth.

If you use standard h1-h6 headings in your topics, then using the Flare default values with TOC-depth will result in a lot of extra headings from the h2-h6 styles in your printed contents that doesn't match your TOC file.

In my projects, I found that this worked for me:
- Set the mc-heading-level property in h2-h6 to 0.
- Create new h1 style classes (e.g. h1.TOC2, h1.TOC3, etc) and set the mc-heading-level property in these styles.

So you would have:

Code: Select all

h2, h3, h4, h5, h6 { mc-heading-level: 0;}

h1 { mc-heading-level: 1;}
h1.TOC2 { mc-heading-level: 2;}
h1.TOC3 { mc-heading-level: 3;}

etc.

When the TOC-depth feature changes the styles in the output, it will change the h1 style to the appropriate h1.TOCn style. It won't change h1 to the h2-h6 styles, so these won't be modified or appear in the print contents.

Note that your topics must only use the h1 style, don't apply the h1.TOCn styles manually.

[John P]

Hello Dave,

Thanks for your response. I tried this method, but haven't been able to get Flare to stop automatically converting my h1 headings to h2-h6 in PDF output. I am using Flare v7, by the way.

Here is my CSS:

Code: Select all

h1
	{
		page-break-before: always;
		mc-heading-level: 1;
	}
h2
	{
		font-size: 12pt;
		mc-heading-level: 0;
	}
h3
	{
		mc-heading-level: 0;
	}

h4
	{
		mc-heading-level: 0;
	}

h1.TOC2
	{
		mc-heading-level: 2;
		page-break-before: avoid;
	}

h1.TOC3
	{
		mc-heading-level: 3;
	}

h1.TOC4
	{
		mc-heading-level: 4;
	}

Yet, when I create PDF output with "Use TOC depth for heading levels" enabled, the result is a Table of Contents that only shows the upper-most indent level topics (In this case, the Welcome topic and the Index). In the body, the topic headings (h1) have still been converted to h2 to h6.

[msievers]

John P -
I'm trying to accomplish the exact same thing with a help system that wasn't designed to be printed. ...but to satisfy a customer request....

At any rate, I've had the same problem. Flare ignores the h1.TOCn styles. Is there an additional setting somewhere that I am missing? I've double- and triple-checked my medium, made sure I have the correct medium set in the target, and so on. Manually assigning h1.TOCn to topics (replacing h1) isn't a good work-around for us as there are several topics that show up more than once in the TOC, and not always at the same level.

Setting h2-h6 to mc-heading-level: 0 results in a single-level TOC. But setting them with values means that the subheads in my topics (currently using h2-h6) are included in the TOC as well as the topic headings themselves (all using h1).

The PDF is just over 1200 pages, so losing the TOC altogether isn't a viable solution and even if it was, deeply nested topics no longer have obvious headings as you scroll through the document.

Were you able to resolve this for your output?

Thanks so much!

[NorthEast]

You need to select Use TOC depth for heading levels on the Target Advanced tab.
If you don't select this, you'll get a single level TOC.

Do not manually assign the h1.TOCn styles in your topics; use the plain h1 style.

[msievers]

Here's what I have set in my Print medium:

h1 to mc-heading-level:1
h1.TOC2 to mc-heading-level:2
h1.TOC3 to mc-heading-level:3
h1.TOC4 to mc-heading-level:4
h2-h6 to mc-heading-level:0 (I only want topic titles in my TOC, not subheads within those topics)

I've changed the formatting of the h1.TOCn styles to be crazy colors to help identify them in the output and have left the h2-h6 settings as is.

In my Target, the Medium is set to Print and Use TOC depth for heading levels is selected.

When I generate the PDF, I get a single-level TOC (I assume because h2-h6 are set to 0) and all topics except those at the highest level are using h2-h6 for the topic titles. There are no crazy colors.

In the topics themselves, I ONLY use h1 for the topic title. Topic titles never use another heading style and h1 is never used for another purpose. Subsequent headings in topics use h2-h6.

SO, I must be missing something (obvious) somewhere. A single-level TOC is better than one with 800 entries for topics and their subheads, but when I drill down a topic at level 3 looks no different than the h3 subhead in the preceding topic. In theory, I was hoping that the first level topics would use h1, second level would use h1.TOC2, third level would use h1.TOC3 and so on.

[LTinker68]

h1.TOC2 to mc-heading-level:2
h1.TOC3 to mc-heading-level:3
h1.TOC4 to mc-heading-level:4...
In my Target, the Medium is set to Print and Use TOC depth for heading levels is selected.

When you have the "Use TOC depth..." option enabled, I don't think it's looking at the mc-heading-level to determine what the next level is -- it's strictly going by the base heading styles. So when you build the output, <h1 class="TOC2"...> is being changed to "<h2 class="TOC2"...>, and since you don't have h2.TOC2 defined in the stylesheet, then it's using the styles for the base h2. If you want those TOCn styles to be used, you need to make them generic classes, instead of tying them to the h1 tag. So your styles in the stylesheet would be:

h1 { color:black; }
.TOC2 { color:red; }
.TOC3 { color:fuschia; }
.TOC4 { color: teal; }
h2 { colore: green; }

Because the TOCn styles are generic classes, they'll work with whatever heading level they end up being paired with as part of the "Use TOC depth..." feature. EDIT: HOWEVER, do not use .TOC2, etc., for the class names -- you'll get a conflict with the p.TOCn styles mentioned below.

EDIT...

When I generate the PDF, I get a single-level TOC (I assume because h2-h6 are set to 0) and all topics except those at the highest level are using h2-h6 for the topic titles. There are no crazy colors.

I missed this line before. If you're trying to style the TOC entries and not the headings, then you need to modify the p.TOC1, p.TOC2, etc., styles in the stylesheet. Those styles are tied to the mc-heading-level, so if you want your second level entries to be indented, then you add a margin-left value to the p.TOC2 style. So h1, h2, h3, etc., control the appearance of the heading in the topics themselves. Styles p.TOC1, p.TOC2, p.TOC3, etc., control the appearance of the corresponding TOC entry in the generated print output (those styles don't affect online outputs). The generated TOC only cares about the content of the h1 tag in the topic, not how the h1 tag is styled, so if your h1 tag is set to italicize the heading, the corresponding TOC entry won't be italicized. You have to italicize the p.TOCn style to make its text italicized.

[NorthEast]

When you have the "Use TOC depth..." option enabled, I don't think it's looking at the mc-heading-level to determine what the next level is -- it's strictly going by the base heading styles. So when you build the output, <h1 class="TOC2"...> is being changed to "<h2 class="TOC2"...>, and since you don't have h2.TOC2 defined in the stylesheet, then it's using the styles for the base h2. If you want those TOCn styles to be used, you need to make them generic classes, instead of tying them to the h1 tag.

No, that's not correct - I use the method I described above, and the Use TOC depth... setting does change h1 styles to h1.TOC2, h1.TOC3, etc.

Using generic classes will not work, they must be h1 tag classes.

In theory, I was hoping that the first level topics would use h1, second level would use h1.TOC2, third level would use h1.TOC3 and so on.

Yes, this is what will happen.

I've noticed some unusual behaviour when I've used this method, which seems to be related to topic stylesheet links, and whether you have a master stylesheet set (in the target/project).

For me, it works when:
* All topics include a stylesheet link; i.e. in the topic properties, there is a stylesheet set and it is NOT (Default).
* There is NO master stylesheet set on either the target or project; i.e. in the target/project properties, the master stylesheet is set to (Default).

If I set a master stylesheet, it stops working - so clearly there is some sort of glitch in Flare.

[LTinker68]

When you have the "Use TOC depth..." option enabled, I don't think it's looking at the mc-heading-level to determine what the next level is -- it's strictly going by the base heading styles. So when you build the output, <h1 class="TOC2"...> is being changed to "<h2 class="TOC2"...>, and since you don't have h2.TOC2 defined in the stylesheet, then it's using the styles for the base h2. If you want those TOCn styles to be used, you need to make them generic classes, instead of tying them to the h1 tag.

No, that's not correct - I use the method I described above, and the Use TOC depth... setting does change h1 styles to h1.TOC2, h1.TOC3, etc.

Oh, sorry, then. I wonder if that changed from before or if it was always that way.

[msievers]

I'm pretty sure I just heard angels singing. It was the master stylesheet that was getting in the way. I removed it from the project level, assigned it to the topics themselves, and voila! (my target was already using default) Luckily, that also resolved the issue with Xrefs not showing a topic title b/c it couldn't find the h1.

Thank you all SO, SO much!

Meghan

[NorthEast]

I'm pretty sure I just heard angels singing. It was the master stylesheet that was getting in the way. I removed it from the project level, assigned it to the topics themselves, and voila! (my target was already using default) Luckily, that also resolved the issue with Xrefs not showing a topic title b/c it couldn't find the h1.

Thank you all SO, SO much!

Meghan

No problem.

This feature in Flare is one of my biggest gripes. It's remarkably difficult to configure the print TOC to match the structure of your help TOC (and TOC file). I've never understood why the print TOC is generated from heading levels, and you don't have the option to generate it from the TOC file you've already created.

[msievers]

This feature in Flare is one of my biggest gripes. It's remarkably difficult to configure the print TOC to match the structure of your help TOC (and TOC file). I've never understood why the print TOC is generated from heading levels, and you don't have the option to generate it from the TOC file you've already created.

As a former user of RoboHelp and Acrobat, I cannot agree more with that gripe (not that generating one directly from RoboHelp is smooth sailing, but most of my printed books were written in FrameMaker). The difficulty in creating a top-notch TOC and the inability to edit the bookmarks pane is a huge turn-off for me that I wish I'd seen coming before purchasing. I shouldn't be required to go behind Flare's back (so to speak) to get a decent print output with a nested TOC and appropriately styled headings.

That said, I have one now and will be locking it down and saving a copy of the necessary files in the event that catastrophe strikes and I have to start over.

[msievers]

Dave Lee, my PDF now looks great. However, Flare is no longer looking at a secondary stylesheet I use to override some of the Flare settings in styles.css for my HTML5 output. The secondary stylesheet is referenced from the Custom JavaScript box in the skin as follows (I haven't made changes to this since starting work on the PDF and it was working gloriously then):

Code: Select all

$('head').append('<link rel="stylesheet" href="Content/Resources/Stylesheets/Styles_Meghan.css" type="text/css" />');

I also noticed that Flare ignored my breadcrumbs proxy after I removed the master stylesheet from my project and used a default format instead.

I assume both of these things are happening b/c I changed the stylesheet settings on the project and topic levels as it was after this change that I noticed the changes to my HTML5 output. (Although I wouldn't deny other changes as I was doing a good bit of poking around in the project to create an attractive PDF.)

I reassigned the master stylesheet to the project and that resolved the breadcrumbs (a bit of a pain for generating PDF and HTML5 if I have to remember to change that, but I can live with it). I also set all my topics back to the (default) stylesheet. However, Flare is still ignoring my secondary stylesheet when I generate the output. Any ideas? Am I missing something obvious?

Thanks for any help!
Meghan

[NorthEast]

Just to be clear, adding a stylesheet link in the skin's custom javascript section is a method to customise the skin itself - it does not affect topics. This method adds the stylesheet to the main 'container' in the help output, not topic files. It'll also have no effect on outputs that don't use the skin, such as PDF.

The master stylesheet setting is to set stylesheet links in all topics. If you use this, the output will ignore any stylesheet links you have in your topics, and replace it with the master stylesheet. This also prevents you from having more than one stylesheet link in the topic. Setting this also stops custom mc-heading-level settings from working properly in PDF outputs (a bug).

If you set the master stylesheet to (Default), the output will just keep whatever stylesheet link(s) are already set in your topics. So if some topics are not appearing correctly, then perhaps they either don't have a stylesheet link, or are linked to the wrong stylesheet. A quick way to check is to look in the File List view (filtered to show topics), and check the Stylesheet column. Tip: You can apply stylesheets to multiple files in the File List view by setting their properties.

[msievers]

Sorry, I was unclear. The secondary stylesheet I have in the custom JS box is for the HTML5 skin. It modifies settings up in the header near the logo and adds some styling to custom links that are also in that area. It also adds rounded corners and padding to the Nav and content panes.

I have two stylesheets. One (AIMsi) is the default for the project to modify topics. The other (Meghan_styles) is for the HTML5 skin (overriding the styles.css that Flare builds).

I did some more poking around. I noticed that the Do not use "Content" folder in output check box was selected for my HTML5 output. If I clear that check box Flare uses Meghan_styles.css to override settings in Styles.css and display my skin as I intended. That problem is solved.

Here's what I learned about the breadcrumbs proxy in my project.

When >>>

• The project-level css is default.
  The topic-level css is AIMsi.

The breadcrumbs proxy is ignored (breadcrumbs display unstyled below my H1).

When >>>

• The project-level css is AIMsi.
  The topic-level css remains as above (did not change to "default" before setting the stylesheet for the project).

The breadcrumbs proxy is positioned and styled as expected.

Result >>>
It seems that a (default) value for the project master stylesheet causes Flare to ignore my breadcrumbs proxy settings in HTML5 output. It needs to be set to (default) for PDF output for mc-heading-level to work in the TOC and it needs to be set to an actual stylesheet for HTML5 output in order for the breadcrumbs proxy to behave as expected. I'm not sure why it matters when all of the topics are set to use that stylesheet (AIMsi.css), but it seems to. Not a huge deal b/c I can just toggle the project stylesheet depending on the output I'm generating, but it is a little strange.

Cheers
Meghan

[RichardParis]

Hi !

I am a little confused, I am new with Flare. For the PDF output, I would like to the same thing that with the web output TOC. A multiple levels TOC as:
http://screencast.com/t/Ia2HeFVfYB

That’s not possible, or that is not easy to do?

I made a TOC for the PDF target, I choose “Use TOC depth” but I got this result:
http://screencast.com/t/7p2DuWk8fcN4

It seems it use the style, not the TOC.

Did I make a mistake somewhere?

Thanks for your help.

[Pernice]

For me, it works when:
* All topics include a stylesheet link; i.e. in the topic properties, there is a stylesheet set and it is NOT (Default).
* There is NO master stylesheet set on either the target or project; i.e. in the target/project properties, the master stylesheet is set to (Default).

I did this and lost some of the styling in my HTML5 output (for header size and breadcrumbs), so I reinstated the stylesheet on the target (not the project) and it's all good - the PDF still has the right structure in its TOC, the body pages have the right heading styles, and in the HTML5 output I got my styles back.