How do I get my TOC structure in a print output?

[NorthEast]

I'm getting a bit confused with the way you can create heading levels in the TOC proxy.

I want my printed TOC (proxy) to look exactly like my TOC file. I only want h1 topic headings to be listed in my printed TOC, and I want them to appear indented as they are in the TOC file. This seemed like it should be a simple task.

The helps says there are two ways to generate a TOC proxy, (a) you can base them on the heading levels in your topics, or (b) you can base them on the levels in your outline TOC.

I ruled out creating the TOC based on heading levels. I can get it to include all my h1 headings, but they are listed in a flat structure, which is no good as I want it to match the structure in my TOC.

So, I tried the second method to generate the TOC based on my outline TOC heading levels, and I ticked Use TOC depth for heading levels in the target.

What this seems to do is modify all the heading styles in the output (which I don't want), and then generate the TOC based on the modified levels. This made all my topic heading levels indented at their correct levels, but it also meant that I had to include all my other heading styles h2-h6 in the TOC (if I wanted more than one level to appear), which means any sub-headings within my topics are now included in the TOC.

For example, say the structure of my TOC is:

> Topic A heading (h1)
>-> Topic B heading (h1)
>-> Topic C heading (h1)

In the print output I get:

> Topic A heading (h1)
>-> Topic A sub-heading i (h2)
>-> Topic A sub-heading ii (h2)
>-> Topic A sub-heading iii (h2)
>-> Topic B heading (now h2)
>-> Topic C heading (now h2)

So, now the sub-headings in topic A are being included in my print TOC, which I don't want. I only want the original h1 topic titles in my TOC file.

I've gone through the help several times now, is this the way that it is supposed to work?
It seems a bit crazy that there's no way to get your original TOC structure to be used in the print output.

[carolynmwallace]

Hi, Dave! I'm a bit confused by your TOC. You say:

For example, say the structure of my TOC is:

> Topic A heading (h1)
>-> Topic B heading (h1)
>-> Topic C heading (h1)

Are Topics B and C sub-sections of Topic A, as their indents would seem to suggest? If so, shouldn't their headings be "H2," not "H1" even if they are individual topics? And is Topic A the "book" topic (i.e., the one represented by the book icon)?

The way I handle it, to provide another example, is that my "Book" topic (top level) has an H1 heading, and all the topics within that book have H2 headings. So my TOC proxy comes out exactly the way I want it.

[NorthEast]

Are Topics B and C sub-sections of Topic A, as their indents would seem to suggest? If so, shouldn't their headings be "H2," not "H1" even if they are individual topics? And is Topic A the "book" topic (i.e., the one represented by the book icon)?

No, topics B and C are separate topics, and have h1 headings. Topic A is a book, and contains Topic B and C.

Most of my topics have some h2 and h3 headings. All I want is my print TOC to show all my h1 headings (and not h2 or h3), and for it to be indented in the same way as my TOC file.

[KevinDAmery]

Hey Dave,

The behaviour your seeing for TOC Depth is by design. The original request for this feature was to be able to set the hierarchy levels of the content by promoting or demoting it in the TOC, so that the writer didn't have to go through all the topics and make sure that the headings match the TOC level. Basically, the intent was to let the writer control the entire structure of their document by their work in the TOC, similar to how you might work in Word using Outline mode.

Obviously, this doesn't match what you want to do with your TOC, but it does match what the original request was. (It was one of the first things I tried helping someone with after I was made an MVP two years ago... ahh, where does the time go....)

[NorthEast]

Thanks.
I'm really quite surprised that you can't create a printed TOC that exactly matches your online TOC.

I suppose one way round it is not use h2-h6 for sub-headings in your topics, so that they're not picked up in the print TOC, but that seems a bit drastic.

[LTinker68]

I suppose one way round it is not use h2-h6 for sub-headings in your topics, so that they're not picked up in the print TOC, but that seems a bit drastic.

Go into the stylesheet and for all those headings you don't want to appear in the TOC, set their mc-heading-level to 0 (for print medium, of course). I think that works regardless of which TOC-build method you use. It definitely works with the use TOC depths option, since that's what I use.

[doc_guy]

Ding ding ding ding ding! The correct answer award goes to Lisa for her mc-heading-level response. It is how I manipulate heading levels in my TOCs and it works just like you are talking about.

[NorthEast]

Thanks, but I've already tried this, and it doesn't work in this situation.

Say my online TOC looks like this:

> Topic A heading (book)
>--> Topic B heading (topic)
>--> Topic C heading (topic)

Topic A, B and C all have h1 headings; and can use h2-h6 sub-headings inside.

Now, say I set h1 with mc-heading of 1, and h2-h6 to have mc-heading-level 0.

If I try the two different methods to create the print TOC:

A) If I have 'Use TOC depth for heading levels' off, my print TOC will look like:

> Topic A heading
> Topic B heading
> Topic C heading

All my topic headings (h1s) are in the print TOC, but it's a flat structure and doesn't match my online TOC - Topic B and C aren't indented inside Topic A (they're all TOC1s).

B) If I have 'Use TOC depth for heading levels' on, my print TOC will look like:

> Topic A

Topic B and C headings aren't included in the print TOC, as they've been modified from h1 to h2 headings, and h2 has a mc-heading-level of 0.

So, the only way to include my Topic B and C headings is to set my h2 style with a mc-heading-level of 2 (in practice I'd also need to enable this for h3-h5 too).

However, if I do this then my print TOC will also include any sub-headings inside the topics which use h2-h6. Their heading levels will be modified, but they are still included in the print TOC.

So I get something like:

> Topic A heading (h1)
>--> Topic A sub-heading (h2)
>--> Topic B heading (h2, originally an h1)
>--> Topic C heading (h2, originally an h1)

The Topic B and C headings are now h2s, and they are indented in the print TOC as I want them to be; however, a sub-heading (h2) in Topic A is now also included in my TOC.
I only want my print TOC to include the topic headings, i.e. what were originally h1s, not any sub-headings inside topics.

The only way round this I can see is not to use h2-h6 inside topics, because you need to have their mc-heading-levels enabled if you want to use the 'Use TOC depth' option (and have a TOC with more than one level).

[KevinDAmery]

Dave, here's a thought: forget about the TOC level feature, and instead create a class to apply to your H1 styles. The only difference between it and the normal H1 is the mc-heading level. This should demote it in the TOC, but allow you to maintain your heading structure for each topic.

Could be a lot of work to go through the topics and apply the class, but it should get you where you need to go at least. HTH.

[NorthEast]

Hmm... I'm not sure that I understand what you mean.


What I'm trying to do is recreate my online TOC structure exactly in my print TOC. In my online TOC, the only entries in my TOC are for topics, and each entry is the same as the topic's h1 heading.

I want my print TOC to be the exactly same. I only want it to include my h1 topic headings, and indent them in the printed TOC as they appear in my online TOC.

Unless I'm mistaken, it appears that the structure (i.e. the indentation of entries) in a printed TOC can only be based on the heading levels used in the topics.

I just use the default heading levels, so all my topics start with an h1, and have h2, h3, h4, etc.

So, with the TOC depth option off, I can have all my h1 headings (topic titles) in the print TOC, but the entries are just in a long list without any indentation - they aren't indented as they are in my online TOC.

With the TOC depth option on, all the heading levels are modified in the output, and whilst my topic headings will now be indented in the print TOC as they are in my online TOC, the print TOC will now also incorporate all heading levels used inside my topics h2, h3, etc. So instead of just getting the topic titles in my print TOC, I also get all the sub-headings inside my topics.

[KevinDAmery]

What I mean is, you create one or two classes of H1 whose sole purpose is to indent their entry in the TOC. For example, h1.level2, h1.level3 etc. In these classes, you change the mc-heading-level parameter from 1 to 2, 3, etc. Then you go to the topics that need to be indented one level in the TOC and apply h1.level2 to the first heading. The net result is that you have h1 styles for your first headings and only h1 appears in your TOC, but the h1.level2 styles get indented in the TOC, as do the h1.level3 styles.

[doc_guy]

Here's what I want to know: you have all these H1's in your content, yet in your TOC they are at different levels.

What does this look like in your printed documentation? Given your example:

> Topic A heading (book)
>--> Topic B heading (topic)
>--> Topic C heading (topic)

Your TOC says that Topic B is a child of Topic A. I'm assuming that it is organized this way because it makes logical sense. Why doesn't Topic B start with an H2, then? You have a hierarchical TOC, but not hierarchical content. Yet you want your printed TOC to enforce a hierarchy that your heading levels don't support.

That said, I do have something similar. I have a hierarchy like yours:

> Topic A heading (chapter)
>--> Topic B heading (topic)
>--> Topic C heading (topic)
> Topic D heading (chapter)
>--> Topic E heading (topic)
>--> Topic F heading (topic)

Each of these topics start with an H1 heading, but my Topic A and Topic D are a class of H1 called H1.Chapter.

For my online content, H1 and H1.chapter have the same font size and settings.

In my printed output, H1 and H1.chapter have different font sizes, and different mc-heading-level properties.

This solution allows my online content to all appear to have the same heading level when you view a topic, but it places a hierarchy in my printed documentation that is reflected in both the printed TOC and in the body content itself (because H1.Chapter has a larger font than does H1).

[NorthEast]

Your TOC says that Topic B is a child of Topic A. I'm assuming that it is organized this way because it makes logical sense. Why doesn't Topic B start with an H2, then? You have a hierarchical TOC, but not hierarchical content. Yet you want your printed TOC to enforce a hierarchy that your heading levels don't support.

Yep, that's probably what I'd do if I was using a print design tool, like writing a chapter in FrameMaker. As I write each 'topic', I would know what heading level to use (from the content around it). The heading levels are very important in this situation because they're used to generate my TOC; I don't have the ability to directly edit/organise my TOC in an editor.

Using Flare is a lot different though. I write each topic in isolation, and I don't necesarily know (or need to think about) what level it'll be placed in the final TOC. I design my TOC structure in an editor, and that's where I decide what topics go where.

Or at least that's how it works if I'm publishing an online output. If I want to publish the same project in a print output, then I use a TOC file with my print target to select which topics are included in my output. So, you'd think the same TOC file could also be used directly as a basis for what appears on the 'Contents' page of my print output, right? Wrong.

I can't actually use the project TOC structure that I designed in the editor. For my print 'Contents' page, I have to generate a TOC that is based on the heading levels in my topics (like I would in FrameMaker). And up to now, the heading levels in my topics have had no particular significance.

So, do I seriously have to open up all my topics, double-check what level they appear in my TOC, and then reapply heading styles? And what if I want to change my TOC structure, do I go back and edit hundreds of heading levels in my topics?
And all this just for my print 'Contents' page to match a TOC structure that I've already designed in an editor.

To me, it just seems like Flare is unnecessarily imposing a workflow from a print design tool. Why do I need to set up and apply specific heading styles in my topics in order to create my print TOC, when I've already spent time designing the TOC structure for my project? This is a single-sourcing tool, but you have two different systems for creating your online and print TOCs, when you should just have one.

Switching on the 'TOC depth' option is a half-way solution to the problem. It'll go through your project and modify all your heading styles into a hierarchical order based on your TOC file. This is pretty handy if you want different heading styles in your print target. The only problem is that when the print TOC is generated, it'll include any subheadings in your topics that use h2-h6 (so it won't match your project TOC).

What I'd like to see is a simple way to use the TOC that you've created in the print output 'Contents' page. For example, you could have something in the contents proxy that says include the entries in my TOC file up to x levels. That's it, no effort in setting up or messing around with styles required.

[KevinDAmery]

Sounds like what you really need is a third state on the TOC level feature (i.e. use project TOC to determine print TOC structure, but don't include other headings). Which I guess means feature request time.

As mentioned, the existing TOC level feature behaves according to a feature request from other users, so I don't see Madcap discarding or changing it. Expanding on it, though, would be a whole other story.

The "modify-headings" workflow that Paul and I were discussing is more of an "ok, the automatic features won't do it for me, how else can I get there?" kinda thing.

[NorthEast]

Yep, thanks.
I'll definitely put in a feature request!

I suppose one solution is just not to use h2-h6 for subheadings in the topics, so they don't get included in the print TOC. Then I know all my heading levels are real topic titles.
It's still a bit of a pain to do, but I'd only have to do it once, and I think editing the levels or classes of topic headings would be a maintenance nightmare.

[KevinDAmery]

Yeah, that would be one option. You could come up with P classes that mimic the appearance of headings but don't have heading level settings applied to them: of course, then you'd have to go modify your topics to replace the existing headings with the new styles, so you're back in the same boat as the heading class suggestion we had earlier (although I suppose you could streamline things with some clever search and replace strings).

[NorthEast]

Yep, I reckon it is the easier option, and it'll mean that I don't have a 25 page TOC!

If I do it this way, then it is a change I only need to do once, and I can use the 'TOC depth' feature to set all my topic headings so that they come out ok in the print TOC.
Not using 'TOC depth' would mean that I have to set all my heading levels manually. This would take a while to do (I can't automate it), and it is a maintenance headache as any changes to my TOC structure means going through the topics again to re-apply heading levels.

[doc_guy]

don't go through your topics to change the headings to something else. Just change the setting in the style sheet mc-heading-level to 0 for h2-h6. That way you can leave your headings in your topics, but they won't show up in the TOC.

[doc_guy]

I thought the thread ended on page 1. I didn't see the two replies above before I posted my latest suggestion... Sorry.

[KevinDAmery]

don't go through your topics to change the headings to something else. Just change the setting in the style sheet mc-heading-level to 0 for h2-h6. That way you can leave your headings in your topics, but they won't show up in the TOC.

Actually, that wouldn't work if you used the TOC level feature, because in the child topics the H1s would dynamically be changed to H2, H3 etc. depending on their place in the TOC hierarchy. Disabling them for the TOC would defeat the purpose (you'd only see the very top level in your TOC).

[Mette Nyberg]

Dave
I am not sure if you can use this approach - but you could try to play a bit with the relevant TOC1, TOC2 (under the p tag). This allows you to adjust the left margin in your printed TOCand indent the second level as you want it. In my project I also have all my topics starting with H1. I did a quick test and created a TOC that mirrors my project TOC (I think that is what you wanted).
A (technically H1 in TOC)
<topics all named Axxxx> all H1 but technically H2 in TOC
B
<topics all nemed Bxxxx> all H1
C
<topics all named Cxxxx> all H1

I selected the option to base it on the toc levels.
I set H1 to level 1 and H2 to 2
When I compile I only get the topics in these two levels - and they all have a H1 heading.
You can set the left indent as you want under the TOC1 and TOC2.
Tip - color code the headings to see what happens.

[NorthEast]

Thanks, it wasn't the formatting of the print TOC, it's what's included in the print TOC.

Basically I wanted what's in my print TOC to be the same as my online TOC, and at the moment the print TOC can only be generated from heading levels. Anyway, MadCap have indicated they'll be adding something in a future version to do this.