Ignore headings to create TOC

[Eric Lachance]

Hi everyone,

I'm kind of new to flare, though I've read the "Five Steps to Flare" and I'm a pretty fast learner. There are a few very frustrating things with Flare6 though, and perhaps someone could help me with one of those frustrations.

I am creating the documentation for a product, which has 2 targets: A PDF and a WebHelp. At the moment, both are producing pretty much the same content - that is, the TOC is the same, and other than conditions for one or two paragraphs (about downloading a PDF or getting the online version) and some style differences, they are pretty much the same.

The issue that I'm having is that I have a TOC created for a reason - to have a TOC. I don't see any reason why I wouldn't be able to tell Flare not to generate a TOC using my <h1> to <h6> tags, but to just use the TOC that I told it to use.

At the moment this mean that I have created p.h1 through p.h6 styles when I want to display something as a header but have it ignored by the TOC Proxy. It's utterly ridiculous - that is, unless someone actually knows of an option that has escaped my thorough search of the options, stylesheets, target and TOC settings.

[LTinker68]

The issue that I'm having is that I have a TOC created for a reason - to have a TOC. I don't see any reason why I wouldn't be able to tell Flare not to generate a TOC using my <h1> to <h6> tags, but to just use the TOC that I told it to use.

I'm not quite sure what you're asking. Are you asking how to add a Table of Contents topic to your print output? To do so, you create a topic file, insert a tocProxy, then add the topic to the TOC. If you don't want that topic to appear in the online output, then you exclude it from online output, so it'll only be used in the print output.

Print outputs only include topics listed in the TOC file associated with that print target. Online outputs include all topics in the output unless they're conditioned out, but the TOC pane itself matches the TOC file associated with that online target. So if you have 10 topics in your TOC, then for print output you'll end up with 10 topics, but for online output you could end up with hundreds, or however many topics are in your project that haven't been excluded from the online output.

[Eric Lachance]

Lisa,

The TOC Proxy in a topic is exactly what I am using, and that is exactly what's failing to meet my basic expectations. The explanation of the problem is harder precisely because the "TOC Proxy" doesn't produce the same output as the "Master.fltoc" TOC file in the project. It's confusing as hell.

So, say that my Master.fltoc looks like this:


This is what I'd expect in the TOCProxy output in the "Table of Contents" page. But this is what I'm getting:



The difference, at the moment, is somewhat minimal - but that's only because I went in myself and changed all the headers (<h3> to <h6>) into paragraph tags so they *wouldn't* appear in the TOC. The difference that does appear is that my topic "Installing the software" in Master.fltoc is ignored, and the TOC contains the two <h2> tags contained in this topic, "Installing <softwarename>" and "Updating <softwarename>". That shouldn't happen, and I don't want it to happen.

What I want is that Master.fltoc be used to generate the TOCProxy instead of the contents of my topics. Header tags (<h1> to <h6>) are used for *formatting*, not *structure*.

[techwriter31]

I'm new to printed outputs too, so hopefully this helps.

You can control what's included in the TOC proxy by modifying the PrintSupport > mc-heading-level property for your heading styles. The value you assign to the mc-heading-level corresponds with how it will appear in the TOC Proxy. If you assign it a value of zero, it will be excluded from the TOC Proxy. For my project, I modified this property in the print medium only.

For example:

h1
{
mc-heading-level: 1;
}

h2
{
mc-heading-level: 2;
}

h3
{
mc-heading-level: 3;
}

h4
{
mc-heading-level: 0;
}

[LTinker68]

I think Eric is talking about the text of the TOC entries themselves. So in the TOC under the Installation and Setup book, the "Installing the software" TOC entry results in a Table of Contents entry of "Installing" and he wants it to be "Installing the software". When you build online output, the text of the TOC entry is used as the text of the resulting entry in the TOC pane. For print output, though, it uses the text in the first heading of the topic.

To be honest, I never really noticed that before, because there's more room in the Table of Contents page of the print output (at least, the way I have it set up), so I didn't worry about shortening the TOC entry in Flare so that it would fit, and I was fine with it using the full heading text in the print TOC.

I don't know if there's a way around this except to have two TOCs in your project, one for online output and one for print. When you drag a topic into the TOC, it will automatically set its TOC entry to match the first heading in the topic, unless you specified something for the <title> tag, in which case it uses the info from the title tag. So set the first heading in the topics to the text you want to appear in the generated print output. Then in the online TOC, when you drag a topic to the TOC file and its entry is too lengthy for the online output, you can override the default entry text with shorter text that you specify in the TOC file. For the print TOC, you just leave the TOC entry to what was brought in from the topic heading. In this case, I wouldn't populate the title tag for the topics, because that'll just put you back where you started with the print output.

In the long term, you can submit a feature request at http://www.madcapsoftware.com/bugs/submit.aspx asking for a setting in the target that when checked will force the generated TOC to match the text entries in the TOC file and not pull info from the topic's heading or title tags.

[NorthEast]

What I want is that Master.fltoc be used to generate the TOCProxy instead of the contents of my topics. Header tags (<h1> to <h6>) are used for *formatting*, not *structure*.

Exactly.
Eric, you're not going mad, this aspect of Flare is quite confusing and isn't very well implemented. I'd certainly put in a feature request to improve it.

The short answer is that you can't directly use the structure of your TOC file as a basis for generating the print TOC. The print TOC is solely based on styles, and isn't related to your TOC file structure.

Now, there is an option in the target (Advanced tab) to Use TOC depth for heading levels. This option modifies the heading levels (in the output only) according to the structure of your TOC file. The heading styles are modified to those in the stylesheet which have the mc-heading-level property set; which by default is h1-h6.

This sounds good, but if you use h2-h6 subheadings within topics, the default settings means the generated print TOC still won't exactly match your TOC file structure. The problem is that all your topic subheadings will also be included in the print TOC, not just the main topic headings (that were h1s) - and you probably just want the h1s for it to match the structure in your original TOC file.

To solve this issue, I've previously posted a method to get the print TOC to include only topic headings, assuming your topics all include h1s.
See here: http://forums.madcapsoftware.com/viewto ... 858#p61748

[Eric Lachance]

Thanks for all the inputs everyone.

I guess at the moment I'm just stuck with it, I've made the feature request and hope it will be implemented in the future.

[NorthEast]

I guess at the moment I'm just stuck with it, I've made the feature request and hope it will be implemented in the future.

You're not entirely stuck - the solution above will create a print TOC that matches your TOC file; and without manually applying any styles like you have been doing.