Why does Flare outputs ALL the topics when building my HTML5

[mechartrand]

Hi!

I have a project with about 2600 topics. I made a small table of content using 26 topics.
When I build the target using that table of content, Flare outputs ALL the topics in my output folder.
I would like it to export only the topics from my TOC.

Is there something I am doing wrong?

Thank you!

Marie-Eve

[Paul Griffiths]

In the Target Editor, on the Advanced tab, select the Exclude content not linked directly or indirectly from the target check box.

[mechartrand]

Excellent! It works!
Thank you very much. You were very helpful and very fast to answer.

I knew I was missing something somewhere.

[LesNoiz]

Including topics in the output that are not in the TOC seems odd, but that is the default behavior in Flare. When told this is what Flare does, I didn't believe it until I tried. Sure enough, all of the topics in the project are included (and are returned in the search results!). Am I the only one who finds this counter-intuitive? What could possibly be the use case for this behavior?

Although there is a workaround, who would think that selecting the Exclude content not linked directly or indirectly from the target check box from the Advanced tab of the Target Editor would fix the problem, or even think of looking there in the first place? What does Exclude content not linked directly or indirectly from the target actually mean? It says nothing about the TOC. I've wasted half a day trying to figure this out. It wouldn't be so bad if this was the only issue I've had with Flare, but this is the umpteenth time I've had so scour the documentation, the web, and these forums to try and figure out some strange behavior. I have never encountered a product that is so hard to learn and use, and that has so many gotchas.

How many people out there are using conditions to fix this behavior, or are publishing projects without realizing that they include information that should not be there?

Can anyone (someone from Flare hopefully) comment on why this is the default behavior? It just seems so wrong (and dangerous).

[Nita Beck]

Can anyone (someone from Flare hopefully) comment on why this is the default behavior? It just seems so wrong (and dangerous).

I'm not a MadCap employee, but I'll jump in.

To the best of my knowledge, the convention of having all topics in a project included in a generated Help system has a long history, predating Flare. Although I haven't used RoboHelp for a few versions now, I'm pretty sure that this is also how RoboHelp works. And I think this is also how Microsoft's HTML Help workshop works. It's not that the MadCap folks dreamed up this default behavior on their own. I think they just followed the prevailing convention.

The design assumption, I'm guessing, was that if an author had a topic in a project, it was assumed that he or she wanted that topic in a generated Help system. There could be many topics that the author wanted included in the generated Help but without having them show up on the TOC; perhaps a subset of topics would be accessible only through the index or only through a search or only through links supplied in other topics.

For Help authors who have been around the block many times (... the "old dogs" like me), this default behavior was widely understood, so we regularly turned to conditions to keep topics out of a Help system.

A few versions back, Flare added the "Exclude content not linked directly or indirectly from the target" option, which gave us a new and different way of controlling which topics would end up in our Help systems. (I won't get into the complexity of using both this option and conditions at the same time; I do it all the time, but one has to pay attention so as not to make things overly complicated. But I digress...)

This option means that the only topics that will be included are those explicity named in the target (so that's only the "startup topic"), those topics included on the TOC that is associated with the target (unless conditioned out), and those that are not on the TOC but are linked to from topics that are on the TOC.

Hope this helps...

[i-tietz]

Including topics in the output that are not in the TOC seems odd, but that is the default behavior in Flare. When told this is what Flare does, I didn't believe it until I tried. Sure enough, all of the topics in the project are included (and are returned in the search results!). Am I the only one who finds this counter-intuitive? What could possibly be the use case for this behavior?

All sorts of non-print help are not linear, their basic principle is hypertext - pretty difficult if not impossible to be pressed into a linear TOC structure.
If your content is still linear but you publish it to HTML 5, you're actually sort of using a spoon to bang a nail into the wall. Of course you CAN do that, but actually those two things don't really go together well.
But we're in the age of single-sourcing, so we have to pay that price.

Use-case:
---------------------------------
We have projects that contain several thousand topics:

About 25% of them are called contextsensitively (CSH for windows or tabs or ... ).

The rest comes as
- popups (for field help) inside a CSH topic (for windows or tabs, etc.)
- "background" topics
- examples
And a handful of topics contains only parts of a GUI description, because some GUIs are just too complicated to have it all in one VERY LONG topic. - So we split them up.

We do not really want to enter all those topics into the TOC ...
And: Where's the good in there for the user? He woudn't find his way through all those topics anyway ...
-----------------------------------------

As for the search:
There was an option for Webhelp to include only certain topics/templates in the search. That won't work for HTML Help target, but all the others really should work. - Would surprise me if HTML 5 was an exception to that rule.

[i-tietz]

It wouldn't be so bad if this was the only issue I've had with Flare, but this is the umpteenth time I've had so scour the documentation, the web, and these forums to try and figure out some strange behavior. I have never encountered a product that is so hard to learn and use, and that has so many gotchas.

Flare is a tool which has TONS of possibilities and features. Finding your way through it on your own could easily have you passing an elegant solution and heading for the complicated workaround.
I can REALLY, REALLY recommend getting a trainer to come to you or you to go to a MC seminar or to a seminar from a reseller or both (first a general one, then a specific one for your needs)!!! Costs money, yes, but SAVES TIME AND NERVES!!!
And you should also get around to the odd lesson in CSS.

[Nita Beck]

Use-case:
---------------------------------
We have projects that contain several thousand topics:

About 25% of them are called contextsensitively (CSH for windows or tabs or ... ).

The rest comes as
- popups (for field help) inside a CSH topic (for windows or tabs, etc.)
- "background" topics
- examples
And a handful of topics contains only parts of a GUI description, because some GUIs are just too complicated to have it all in one VERY LONG topic. - So we split them up.

We do not really want to enter all those topics into the TOC ...

<slap_on_head>Doh! You're so right, Inge.</slap_on_head>

I have a very similar use case. I've got one Flare project that has more than 200 "field-level" Help topics that are not linked from any TOC, are not linked from any other topic, are not included in the index, and are excluded from search. They are SOLELY for the programmers to hook up to fields in the application's UI. For the target, I do not set the "Exclude content..." option.

--------------

To distill my prior comment in this thread, the original intention of a TOC in a Help authoring tool's project (Flare, RoboHelp, whatever) was to control what would appear in the navigation pane in the Contents. That's it. It was never originally intended to control what would or would not be built into a generated Help system.

[techwriter31]

On a related topic - I recently discovered that Flare also includes your .css files in Webhelp Plus and HTML5 searches if the .css files do not reside in the default Content\Resources\Stylesheets directory. According to tech support, only the server-based outputs are affected by this issue because they make use of Windows Search instead of a search algorithm provided by Flare.

Tech support entered a feature request for this issue.