mini-toc proxy not working as expected in Word output

[gabeanderson]

Hi There-

I've successfully added an "output toc proxy" to my project for a master table of contents, but I can't get anything to appear in my Word output for my "mini-toc proxy."

I've followed the steps in the documentation ("Creating a Mini-TOC for Print Output") and want to use the "Example—TOC Structure Method" outlined in that section of the doc - to create the mini-TOC from the topics in the section, each of which has an H2 header.

My target output has the "Use TOC depth for heading levels" option selected under Printed Out, so I'm not sure what I'm missing.

See attached screenshots.

Any suggestions?

Thanks,
Gabe

[KevinDAmery]

Mini-TOCs don't work in Word output, unfortunately. I believe they do work in direct PDF output, though (in version 4.x).

[gabeanderson]

Thanks, Kevin. That's too bad!

Although I just changed my output to PDF, left everything else the same, and got the same results... no mini-TOC.

No work-around for getting something similar to work in Word?

THanks,
Gabe

[KevinDAmery]

You can, of course, manually add items to a list at the end of the topic, but that defeats the purpose of having the mini-TOC proxy in the first place.

Unfortunately, there are a lot of things we can do to design topics for online output that simply don't make it to Word. (Divs are another example.)

[LTinker68]

No work-around for getting something similar to work in Word?

I had to fake a mini-TOC in my project because of the way I had my page layouts set up. I ended up using a series of xrefs on a page. I didn't go through the effort of trying to get page numbers for each line and I had to manually add/remove topics from it, but the end result showed up both in Word and PDF outputs.

One word of warning about xrefs, though... There's a bug if you point to a topic that has been removed from the output via a condition tag -- the xref line isn't removed automatically, so I had to add a condition to that line in the fake mini-TOC.

[gabeanderson]

Thanks for the suggestions, Kevin and Lisa!

If we decide to include a mini-TOC (vs. just giving each section page some kind of design treatment), we may just do the manual copy 'n paste approach in Word using the master TOC.

[Landy]

Just wondering if there is any update on this issue and whether MiniTOC proxies work for Word/PDF targets now in Flare 6.1.

I have started using them in a couple of projects and noticed that they do work, but inconsistently. That is, it seems to work for one project, but not for another project with the same setup. In the project that doesn't work, the miniTOC seems to stop after the second item in the minitoc.

Any feedback would be appreciated.
Thanks

[ChoccieMuffin]

I've used them (by accident!) in a PDF and it seemed to work fine for me. Can't say I'm doing anything spectacularly complicated though.

[Andrew]

Just wondering if there is any update on this issue and whether MiniTOC proxies work for Word/PDF targets now in Flare 6.1.

I have started using them in a couple of projects and noticed that they do work, but inconsistently. That is, it seems to work for one project, but not for another project with the same setup. In the project that doesn't work, the miniTOC seems to stop after the second item in the minitoc.

Any feedback would be appreciated.
Thanks

Have you set them to go deep enough into your TOC? They default to 3 layers deep. To find out how many layers deep yours goes, right-click the miniTOC proxy and select Edit Mini-TOC Proxy. Look at the TOC Depth field.

This is also a value you can check in your stylesheet called MadCap|miniTocProxy called mc-toc-depth. There's also an mc-output-support style, and you could theoretically have the Mini-TOC proxy disabled in Word. Both styles are in the Unclassified group in the Stylesheet Editor.

[KL-Evoco]

I am having this same issue in PDF outputs. I checked the stylesheet suggestions Andrew gave.
- mc-toc-depth is set to 3, which is 1 level further than I have.
- mc-output-support is set to all.

I still cannot get any of my mini-tocs to show up. I am working in Flare 6.1.

[Suzetteb]

I'm getting inconsistent results in mine. I'm testing for an import workflow and am able to get it to work for the first chapter, only one entry of at least four in the second chapter and looks like I got the last chapter to finally work.

I'm wondering if this has anything to do with setting the heading levels based on the TOC?

I figure my next step is to blow away my customizations for the miniTOC and try again. By the way, it wasn't working at all after the first chapter and I removed the mini-TOC proxy and resinserted it to get it to partially work.

[Suzetteb]

Okay, there's nothing like trial by fire and hoping we can remember all this information. Anyway, just thought I'd post that I noticed something. When you go into your topic and right-click the mini-TOC proxy, make sure there is a style selected there. If you don't have any options, create one in the Style Sheet Editor. This might help.

Good luck!

[LTinker68]

I'm wondering if this has anything to do with setting the heading levels based on the TOC?

Hmmm. I haven't played with mini-TOCs in awhile, so I just tried it in a test project. I have four topics, all with an h1 tag at the top. Topic 1 is the top-level book and contains a mini-TOC proxy. Topics 2, 3, and 4 are children of that book. If the "Use TOC depth for heading levels" is disabled, then the mini-TOC proxy is blank. If the option is enabled, the mini-TOC proxy is populated. If the option is disabled and I manually change the h1 tag to an h2 tag in Topics 2, 3, and 4, then the mini-TOC proxy is populated. So I'm either not remembering correctly how the mini-TOC proxy works, or something is broken in v6, because originally, the only requirement for it to work was that the proxy had to be a level above the topics it referenced in the TOC. How many headings it populated with depending on how many levels you specified in the proxy. But now it seems that the children topics have to have a lower heading tag, either manually set or changed by enabling the option above.

Upon further study, I've determined that the mini-TOC proxy works the way I remembered it for WebHelp (and presumably HTML Help); however, it's not working correctly for PDF output (didn't test Word output). For some reason for PDF outputs, it's requiring that the children topics contain lower heading tags than the parent topic/book.

The short-term workaround is to enable the option above so that it works for both WebHelp and PDF output. For long-term, I'd submit a bug report to http://www.madcapsoftware.com/bugs/submit.aspx.

[LTinker68]

Okay, there's nothing like trial by fire and hoping we can remember all this information. Anyway, just thought I'd post that I noticed something. When you go into your topic and right-click the mini-TOC proxy, make sure there is a style selected there. If you don't have any options, create one in the Style Sheet Editor. This might help.

Didn't seem to help if the output is PDF and the "Use TOC depth for heading levels" is disabled.

[NorthEast]

So I'm either not remembering correctly how the mini-TOC proxy works, or something is broken in v6, because originally, the only requirement for it to work was that the proxy had to be a level above the topics it referenced in the TOC. How many headings it populated with depending on how many levels you specified in the proxy. But now it seems that the children topics have to have a lower heading tag, either manually set or changed by enabling the option above.

Upon further study, I've determined that the mini-TOC proxy works the way I remembered it for WebHelp (and presumably HTML Help); however, it's not working correctly for PDF output (didn't test Word output). For some reason for PDF outputs, it's requiring that the children topics contain lower heading tags than the parent topic/book.

That's correct for WebHelp/HTML Help, as their TOCs actually use the structure in your TOC file.

However, doesn't the mini-TOC in print outputs just follow the structure of the print TOC, rather than the TOC file?
As print TOCs are based on heading levels (or at least the mc-heading-level property), then the print mini-TOC just follows the same structure as the print TOC; which isn't necessarily the same as your TOC file structure.


(What Flare desparately needs is a way to create print TOCs that match your TOC file, as having to generate TOCs from heading levels is an unnecessarily complicated and poor solution. Why can't it use the structure you've already created in the TOC file?)

[LTinker68]

However, doesn't the mini-TOC in print outputs just follow the structure of the print TOC, rather than the TOC file?
As print TOCs are based on heading levels (or at least the mc-heading-level property), then the print mini-TOC just follows the same structure as the print TOC; which isn't necessarily the same as your TOC file structure.

If that's true then that's not intuitive. You wouldn't (and shouldn't) expect to have to remember how the proxy works for one output type versus another. If the proxy is designed to work on topics located at lower level(s) in the TOC file, then it should work based on the TOC structure in the TOC Editor, not the structure of the generated TOC, regardless of the type of output you're generating. Otherwise, that pretty much forces you to enable the "Use TOC depth for heading levels" option or manually use varying heading tags in your topics, and that may not be what the author wants to do, especially from a single sourcing point of view.

[NorthEast]

However, doesn't the mini-TOC in print outputs just follow the structure of the print TOC, rather than the TOC file?
As print TOCs are based on heading levels (or at least the mc-heading-level property), then the print mini-TOC just follows the same structure as the print TOC; which isn't necessarily the same as your TOC file structure.

If that's true then that's not intuitive. You wouldn't (and shouldn't) expect to have to remember how the proxy works for one output type versus another. If the proxy is designed to work on topics located at lower level(s) in the TOC file, then it should work based on the TOC structure in the TOC Editor, not the structure of the generated TOC, regardless of the type of output you're generating. Otherwise, that pretty much forces you to enable the "Use TOC depth for heading levels" option or manually use varying heading tags in your topics, and that may not be what the author wants to do, especially from a single sourcing point of view.

Well, that's kind of my whole argument against how Flare implements the print TOC (and mini-TOC). I think it's unintuative to first create your TOC file (fltoc) structure for help; but then not be able to use that TOC file as a basis to generate your print TOCs, as these are generated based on a system of heading levels. So if you want your help and print TOCs to match, then you're effectively forced into using a whole system of heading levels in your topics. It makes little sense not to be able to have a print TOC that matches your TOC file; the whole system of using heading levels is unnecessary and just makes things over-complicated.

Anyway, given this is the way Flare generates a print TOC, then the print mini-TOC should at least match the structure of the print TOC (which may be different to your TOC file).

[Andrew]

I think you're both missing the fact that many people have more than one heading inside a topic, and if all MiniTOCs and TOCs work off of your "outline" TOC, you may be missing headings from those display TOCs. Unless I misunderstand what you are saying?

It seems to me that using the actual in-topic heading levels is perfectly sane, and in fact, dramatically superior to simply reflecting your outline TOC, unless you use a separate topic for every heading level. I don't, and it would be a pain for me to work that way in many cases.

[LTinker68]

I think you're both missing the fact that many people have more than one heading inside a topic, and if all MiniTOCs and TOCs work off of your "outline" TOC, you may be missing headings from those display TOCs. Unless I misunderstand what you are saying?

No, for online output it includes the secondary, tertiary, etc., headings in a topic in the generated mini-TOC output if you set that proxy to go more than one heading deep, so it's not strictly based on the TOC outline, other than the proxy has to be a level above anything it's to reference.

[Andrew]

I think you're both missing the fact that many people have more than one heading inside a topic, and if all MiniTOCs and TOCs work off of your "outline" TOC, you may be missing headings from those display TOCs. Unless I misunderstand what you are saying?

No, for online output it includes the secondary, tertiary, etc., headings in a topic in the generated mini-TOC output if you set that proxy to go more than one heading deep, so it's not strictly based on the TOC outline, other than the proxy has to be a level above anything it's to reference.

I'm even more confused -- I thought you were talking about print MiniTOCs? If you select Use TOC Depth for Heading Levels, I'd imagine you would *want* the MiniTOC to also use the TOC depth for its options, right? And if you don't select that check box, you'd want the MiniTOC to use the actual headings themselves, right? What am I missing?

[LTinker68]

I'm even more confused -- I thought you were talking about print MiniTOCs? If you select Use TOC Depth for Heading Levels, I'd imagine you would *want* the MiniTOC to also use the TOC depth for its options, right? And if you don't select that check box, you'd want the MiniTOC to use the actual headings themselves, right? What am I missing?

The fact that the latter doesn't work in print output, but does in online output.

For print output, if you don't enable the "Use TOC depth for heading levels", then in your child topic you would have had to manually set its first heading to be an h2 tag. With the option enabled, it would do that for you. For online output, it doesn't matter whether or not that option is enabled. So as I'm writing topics, I generally start them all with an h1 tag. If I later decide that several topics should be grouped together in a book and the book topic could use a miniTOC, then I have to either manually change the topics' first headings to an h2 tag so it'll work in print output -- which now screws up my online output because I want h1 at the top of all topics -- or I have to set the TOC depth option for print output, which may force me to restructure my TOC so that I don't end up with too many levels deep inside a book because that option will now affect the headings in the print outputs.

Whereas enabling the TOC depth option is an easy enough fix to implement in the short-term, it's forcing people into a behavior that they may not want to do (enabling the option or manually planning their headings in the topics ahead of time). And everyone would have to remember that for online output they don't have to enable that option, but for print output they do want to enable it. If you set that up in the first month of a project you work on for a year then start a new project, are you going to remember to do that in the new project, or are you going to come back to this forum to figure out why the print mini-TOC isn't working in one project but is working in another?

Basically, I want it to work as you mention for the print output but it doesn't work that way -- the child topic has to begin with an h2 tag, whether you manually set it to that tag or used the TOC depth option to do so. For online output, it just doesn't care.

[NorthEast]

I think you're both missing the fact that many people have more than one heading inside a topic, and if all MiniTOCs and TOCs work off of your "outline" TOC, you may be missing headings from those display TOCs. Unless I misunderstand what you are saying?

It seems to me that using the actual in-topic heading levels is perfectly sane, and in fact, dramatically superior to simply reflecting your outline TOC, unless you use a separate topic for every heading level. I don't, and it would be a pain for me to work that way in many cases.

Not at all, I'm only too well aware of that fact; I found using sub-headings inside topics to cause a major headache when trying to create print TOCs.

I guess it's how you like to work - to me it seems a bit insane that you can't simply create a TOC file, and have your print TOC look the same as your help TOC (without a lot of fuss).

It doesn't make sense to me, because Flare has a TOC editor in which you create your TOC structure; and it would seem logical to want to use that exact structure for both your help and print outputs. What I see in my TOC file, I want to see in the TOCs in both my help and print targets.

Maybe this example will help explain what I mean...


Say I create 3 topics. I start each topic with a h1 heading, and I use some h2 sub-headings inside these topics.

I set up my TOC file with one topic inside the other, like this:

Topic A
> Topic B
>> Topic C

Ok, so that's my structure, and I want to see that in the contents of both my help and print outputs; I just want to see the topic headings, indented the same way.

Now, all looks fine in the help, but when I come to make my print output, the print TOC on my contents page looks like this:

Topic A
> Sub-heading in topic A
Topic B
> Sub-heading in topic B
Topic C
> Sub-heading in topic C

So, it doesn't follow the structure I set up in my TOC file; the topics are all on the same level (as they're all h1s), and it's also including the sub-headings (h2s) inside my topics.

So instead, I try using the 'Use TOC depth' setting; but with that I get the following:

Topic A
> Sub-heading in topic A
> Topic B
>> Sub-heading in topic B
>> Topic C
>>> Sub-heading in topic C

Ok, now the topics headings (h1s) are correctly indented to match my TOC file structure; however, I've still got the sub-headings in there, and they're all mixed-in with the h1 headings that I want.


To fix all this and have my help and print TOCs match, I have to either; fundamentally change how I use styles in my entire project, or devise a workaround using extra styles with appropriate mc-toc-depth settings (I use this in practice).

But I really don't think the process should be this difficult; why do I have to set up a system of using styles in my project in order to recreate a TOC structure, when I've already created that structure in the TOC file?
I would think the option to have a print TOC that's based on your actual TOC file would be much simpler and make a lot of sense. Otherwise what's the whole point of setting up a TOC file when it comes to print outputs? That only makes sense in Frame/Word, where you don't have an editor to create your TOC structure, and so heading levels are fundamentally important.

[LTinker68]

I agree with all that. The TOC for print output would still determine what's in the output -- if it's not in the TOC then it's not in the generated print output -- whereas online help includes everything by default. And you can override either default behavior using conditional tags. In addition, the headings in all topics should remain as they are in the topics unless you enable the "Use TOC depth for heading levels" option for a particular target.

[Andrew]

So the problem is that, when you set things to use TOC levels, the output TOC gets too deep with your headings because the mc-toc-depth setting is looking at the mc-heading-level property for each header, and not accounting for the fact that using your TOC-defined level has bumped all the headings up a level (or two, as you go down the chain). Basically, you don't want those lower headings to display in the TOC? And the ideal solution would be to force the TOC / MiniTOC to only look at the TOC outline?

[LTinker68]

And the ideal solution would be to force the TOC / MiniTOC to only look at the TOC outline?

I personally don't have a preference -- I just want it to be consistent between online and print outputs so I don't have to remember or plan around the inconsistencies in order to have a truly single sourced project.