Non TOC topics appear in Search

This forum is for all Flare issues related to the HTML5, WebHelp, WebHelp Plus, and Adobe Air Targets
hranga81
Propeller Head
Posts: 35
Joined: Tue Mar 20, 2012 11:17 pm

Non TOC topics appear in Search

Post by hranga81 »

Hi,
We are using one project and all the topics are under that. When I give a build for a particular version, I form a new TOC for that release and include only the topics that i want. I build the Target and the web help displays everything alright. The trouble is when I do a search. The search results display a list of topics; the topics that aren't part of the TOC also appears in the search results. If I click on that topic, it displays the content. Why is it showing up on my web help when I didn't even include that topic? Your help is much appreciated.

Thanks,
Harini
whunter
Sr. Propeller Head
Posts: 429
Joined: Thu Mar 12, 2009 4:49 pm
Location: Portland, OR

Re: Non TOC topics appear in Search

Post by whunter »

When generating online outputs (as opposed to print), by default ALL topics are included in the build, regardless of whether they are in your TOC. If you do not want this behavior, then you can do one of the following:

* Set up conditions in your project and then use those conditions to exclude the topics you don't want in a particular target.
OR
* In your target, on the Advanced tab, select "Exclude content not linked directly or indirectly from the target".
hranga81
Propeller Head
Posts: 35
Joined: Tue Mar 20, 2012 11:17 pm

Re: Non TOC topics appear in Search

Post by hranga81 »

Hi,

Even after applying conditionals at the TOC level and also selecting the "Exclude content not linked directly or indirectly from the target" check box, the excluded topics show up in the Search. What can I do about it? Do I need to set conditionals at topic levels in addition to the TOC? I have so many files, it would be really time consuming. Is there any other alternative?

I have one more query - I have a master TOC. I want to create customized online help for various clients. From the below listed options, which is the best way to go about it?
  • Create 10 condtionals for 10 clients
  • Create 10 TOCs and link each other [If that is even possible]
  • Create 10 TOCs and 10 Targets [Ideally, I don't want to do this]
Kindly guide me through it.

Thanks in Advance,

Harini
LTinker68
Master Propellus Maximus
Posts: 7247
Joined: Thu Feb 16, 2006 9:38 pm

Re: Non TOC topics appear in Search

Post by LTinker68 »

hranga81 wrote:... the "Exclude content not linked directly or indirectly from the target" check box, the excluded topics show up in the Search.
I don't use that feature, but I'm assuming that if the topic is in the search then it's in the output. If you click on the search result, does it bring up the topic? If it does, then it means the topic was linked to from one of the other topics in some way (hyperlink, xref, "related topics" effect, etc.). To check, right-click on the topic in the Content Explorer and select the File Links option or whatever it's titled (I don't have Flare open at the moment to check). That will show you which topics are linked to this topic in some manner. If any of those topics are in the TOC or link to a topic that's in the TOC, then this topic will be added to the output. To me, I prefer using conditions because you have an easy visual cue (if you have condition indicators turned on) about which topics will appear in which outputs. You can also use the File List option to select multiple topics at the same time and apply the same condition to them, so you don't necessarily have to condition them one at a time.
Image

Lisa
Eagles may soar, but weasels aren't sucked into jet engines.
Warning! Loose nut behind the keyboard.
hranga81
Propeller Head
Posts: 35
Joined: Tue Mar 20, 2012 11:17 pm

Re: Non TOC topics appear in Search

Post by hranga81 »

Thanks Lisa,

Only the topics that are referred to and linked are coming up in the search.

Do you think I can manage conditioning one TOC for many variants of online help for clients? What will happen if a particular topic is conditioned with 4 tags? Has anybody tried conditioning set of topics with multiple condition tags? Is it even the right way to do?

Kindly clarify.

Thanks,
Harini
LTinker68
Master Propellus Maximus
Posts: 7247
Joined: Thu Feb 16, 2006 9:38 pm

Re: Non TOC topics appear in Search

Post by LTinker68 »

I prefer one TOC because then I don't have to switch back and forth between TOCs when adding new topics. However, I don't have a lot of conditions. If you have a lot of conditions, then separate TOCs will be easier to maintain, especially if you have conflicting conditions. The hardest part about conditions is knowing that an explicit include overrides an explicit exclude which overrides an implicit include. If you have a lot of conditions, then that might lead to some confusion, because you expect a topic to not be include in a certain output, but the reason it's included is because it has an explicit include. So it comes down to how many conditions and how complex the situations are.

But again, conditioning out a topic on the TOC doesn't affect what topics are included in the online output (it just hides the TOC entry). Conditioning out a topic on the TOC will affect print outputs, because the TOC determines what is included in the print output. If you have a lot of or conflicting conditions on topics, then you might want to use that "Exclude content not directly or indirectly linked to from the target", or however that option is worded. That might make things easier if there are conflicting conditions.
Image

Lisa
Eagles may soar, but weasels aren't sucked into jet engines.
Warning! Loose nut behind the keyboard.
hranga81
Propeller Head
Posts: 35
Joined: Tue Mar 20, 2012 11:17 pm

Re: Non TOC topics appear in Search

Post by hranga81 »

Thanks for the prompt reply Lisa! For now, it is not complicate. I think, one TOC might be good until more variants are needed.

Harini
Rona Kwestel
Sr. Propeller Head
Posts: 212
Joined: Wed Apr 04, 2007 11:50 am

Re: Non TOC topics appear in Search

Post by Rona Kwestel »

I don't know if anyone else would find this useful, but I just submitted the following related feature request, with the subject "Add a TOC topic property to convert any links to other topics not otherwise included to plain text":
The "Exclude content not linked directly or indirectly from the target" option is not granular enough to get the results you want. It's very hard to prevent an unintended cascade of linked topics when including a topic with unwanted links in the TOC for a particular target. The only way to control it is to use a set of complex conditions that then require including/excluding the linked/unlinked versions of the same text in every other target that includes that topic.

To explain the situation more specifically, I have a topic that is part of a series of related topics that all link to each other. In the normal target where this topic would be included, all the related topics would also be in the TOC, so the links are fine. In another target, I would like to include this one topic for reference and not have it link to the related topics, which I don't want to include in this target.

I'd like to be able to create a TOC for this target in which I mark this topic as "Standalone", meaning any links to other files not otherwise included by virtue of being in the TOC or linked to from other non-standalone topics should be converted to plain text and thus those no-longer-linked files should not be pulled into the output.

For example:

File A.1 links to files A.2, A.3, and B.1.

Target B points to TOC B, which includes files B.1, B.2, and A.1, and the entry for A.1 has the "Standalone" property set.

The output includes files A.1, B.1, and B.2, where file A.1 still links to B.1 since it's included in TOC B, but the links to A.2 and A.3 are rendered as plain text and files A.2 and A.3 are not included in the output.
Feel free to submit it as well if you want to bump its priority: https://www.madcapsoftware.com/feedback ... quest.aspx
doc_guy
Propellus Maximus
Posts: 1979
Joined: Tue Nov 28, 2006 11:18 am
Location: Crossroads of the West
Contact:

Re: Non TOC topics appear in Search

Post by doc_guy »

Rona,

You would end up with broken links in your output. Wouldn't that confuse your users? Or if it was converted to text like you suggest, the surrounding text makes it sound like it should be a link, but it's not a link, which would also be confusing for your users.
Paul Pehrson
My Blog

Image
Rona Kwestel
Sr. Propeller Head
Posts: 212
Joined: Wed Apr 04, 2007 11:50 am

Re: Non TOC topics appear in Search

Post by Rona Kwestel »

Fair point, Paul, but I think you can manage that with the proper wording. I tend to prefer links on the word(s) in the context of the sentence rather than explicit referrals to some other location, like "See Hyperlinks for more information." So in the former case, the user would not realize that the link was removed, but in the latter case, it does seem like we're referring them to some other piece of information that we're not including in this output, so if the link is removed, it will be a little awkward.

But fear not; I think the odds of MadCap implementing this not-so-easy-to-code feature are close enough to zero.
kmorrison
Sr. Propeller Head
Posts: 104
Joined: Mon Nov 11, 2013 3:04 pm
Location: Ottawa, Canada
Contact:

Re: Non TOC topics appear in Search

Post by kmorrison »

There's also an option to just exclude a particular topic from the search, but not exclude it from the output, so any links to it won't be broken.

In the Properties of the topic, on the Topic Properties tab, there's a check box labeled "Include topic when full-text search database is generated."

If you clear this box in a topic's properties, it won't show up in the search results. This is unrelated to its presence or absence in the TOC.
Rona Kwestel
Sr. Propeller Head
Posts: 212
Joined: Wed Apr 04, 2007 11:50 am

Re: Non TOC topics appear in Search

Post by Rona Kwestel »

Interesting, except it's at the topic properties level, not the TOC level, so the setting then applies to all outputs that include that topic, which may not be what you want. In outputs that include that topic explicitly in the TOC, you'd want it to be included in the search.

And this doesn't help with a PDF target. If topic A links to topic B and I only include topic A in my PDF TOC, topic B doesn't get pulled in, and I end up with a broken link to it in topic A.

The only way I can find to fix this is to tag every link where this may potentially occur with a condition that I then exclude in the target, and check the non-default option of "Unbind" instead of "Remove" for the "Exclude Action" in the condition dialog for that conditioned link (as found here: viewtopic.php?f=75&t=30388). And even if I were willing to do all that work, suppose I decided to include topic B after all? If I then wanted that link to be active, I'd have to either remove the condition on it, or perhaps not exclude the condition that I tagged it with, but that might affect other such conditioned links. It's just a lot more work and a lot less flexible than the solution I'm proposing.
doc_guy
Propellus Maximus
Posts: 1979
Joined: Tue Nov 28, 2006 11:18 am
Location: Crossroads of the West
Contact:

Re: Non TOC topics appear in Search

Post by doc_guy »

Let me preface this by saying I tried for over two hours trying to make this work, and I couldn't find a way. However, I'll tell you my findings, and maybe somebody smarter that I can take that to the next level and give you the answer you need.

First, I'll speak to cross references, because that is what we use in our project, so it was easy for me to begin testing there.

I'm looking at the temporary HTML files Flare generates when it is building the PDF output, and there is a difference I can see between cross reference links that DO resolve within the PDF, and cross reference links that DON'T resolve in the PDF.

Here is a cross reference link that does resolve to another location in the PDF target:

Code: Select all

<MadCap:xref href="file:///<path>/r-validation-results-tpp.htm" MadCap:xrefTarget="Review validation results">"Review validation results" on page 1</MadCap:xref>
Here is a cross reference link that does NOT resolve to another location in the PDF target:

Code: Select all

<madcap:xref href="file:///<path>/c-cert-domain-components-about.htm">About Domain Components</madcap:xref>
Notice that when Flare knows the target topic is in the PDF, it adds the MadCap:xrefTarget attribute to the element. So what I'm thought was that you could use the CSS attribute selector to differentiate between links in the PDF that resolve to other topics and links that don't resolve to other topics.

The code I tried was this:

Code: Select all

@media print
{
     /* This is the style for links that do not resolve to another place in the PDF */

     MadCap|xref {
         color: black;
         text-decoration:none;
     }

     /* This is the style for links that do resolve to another place in the PDF */

     MadCap|xref[MadCap|xrefTarget] {
        color:#e98300;
        text-decoration:underline;
     }
}
That didn't actually work when I generated the PDF. I'm not sure why not. I tried several permutations of the code to see if I could get it to work, and I can't get it to recognize the attribute selector. I even tried opening the code of the PDF to see if I could make any sense of it. I could not.

I got even less far with your actual question of using direct links. Flare doesn't differentiate in the intermediary HTML file between regular links that resolve to a place in the document and regular links that resolve to a place outside the document. At some point it recognizes it, because when I preview the PDF in Chrome, links that work have a mouse hover over effect, and links that don't work don't have the mouse hover over effect. I just don't know how to differentiate between the two using a style, because I can't find any way in which they are different, at least in the files we have access to (source, and intermediary HTML files).

Sorry. I wish I had better news.
Paul Pehrson
My Blog

Image
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: Non TOC topics appear in Search

Post by NorthEast »

Rona Kwestel wrote:And this doesn't help with a PDF target. If topic A links to topic B and I only include topic A in my PDF TOC, topic B doesn't get pulled in, and I end up with a broken link to it in topic A.

The only way I can find to fix this is to tag every link where this may potentially occur with a condition that I then exclude in the target, and check the non-default option of "Unbind" instead of "Remove" for the "Exclude Action" in the condition dialog for that conditioned link (as found here: viewtopic.php?f=75&t=30388). And even if I were willing to do all that work, suppose I decided to include topic B after all? If I then wanted that link to be active, I'd have to either remove the condition on it, or perhaps not exclude the condition that I tagged it with, but that might affect other such conditioned links. It's just a lot more work and a lot less flexible than the solution I'm proposing.
I might be misunderstanding the thread here, but doesn't Flare already handle this by converting the links to plain text?

If you set a condition on the topic file (in topic properties), not the TOC item, then any links to that topic are converted to plain text.

So you don't need to set conditions on the links, just on the topics themselves.

This works for help and PDF outputs.
doc_guy
Propellus Maximus
Posts: 1979
Joined: Tue Nov 28, 2006 11:18 am
Location: Crossroads of the West
Contact:

Re: Non TOC topics appear in Search

Post by doc_guy »

The problem is when you aren't using conditions on your topics. For example, we have one product, and we have topics that might appear in any of 12 PDF guides. They all build into one online help system. The individual PDF TOCs are all part of the master online TOC.

We don't want to create conditions for each of the books, because, well, we have thousands of topics and it would be a pain trying to keep track of what topics go in which books, and which ones go in multiple books, and if you add a topic to another book, you have to remember to change the conditions on the topic.... all just so that you can get links to render correctly in PDF output. We wouldn't have any other use for the conditions because we never publish any of the individual PDF guides as separate help systems.

Really, it shouldn't require conditions. If a topic in a PDF target is linked to another topic that is not part of the PDF target, Flare should recognize this and render the resulting text as not a link. But it doesn't.
Paul Pehrson
My Blog

Image
Rona Kwestel
Sr. Propeller Head
Posts: 212
Joined: Wed Apr 04, 2007 11:50 am

Re: Non TOC topics appear in Search

Post by Rona Kwestel »

Exactly, Paul. And what I'm suggesting is that I'd like a very similar behavior in HTML output.

In fact, an alternative to what I proposed earlier is to have a target-level checkbox to exclude any topics not directly linked in the TOC, and to perhaps have a way to add non-TOC topics (such as my linked-from-a-toolbar-button doc help topic) explicitly through some other mechanism. Then, any links to topics not explicitly included in the output through the TOC or that hidden topic mechanism should automatically be converted to plain text, and maybe there could be a build report that shows you all the disabled links created by turning on that feature.
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: Non TOC topics appear in Search

Post by NorthEast »

Yep, I'm not questioning the feature request.

I'm just saying that right now this would be handled by using conditions on topics, so you don't need conditions on xrefs.

Depending on the number of xrefs and topics, one way might be easier than another. But I thought marking a topic with a condition might be an easier process than tracking down the individual xrefs to that topic.
doc_guy wrote:The problem is when you aren't using conditions on your topics. For example, we have one product, and we have topics that might appear in any of 12 PDF guides. They all build into one online help system. The individual PDF TOCs are all part of the master online TOC.
So how do you currently handle xrefs to missing topics in this project, or are they just broken?
Rona Kwestel
Sr. Propeller Head
Posts: 212
Joined: Wed Apr 04, 2007 11:50 am

Re: Non TOC topics appear in Search

Post by Rona Kwestel »

For the current case that raised this issue for me, I ended up pulling in all the related topics in a "Reference" section, but it's not ideal and adds content I didn't need/want in that other target.

Regarding your suggestion, I'm not even sure I understand. I have topic A that links to A.1, A.2, and A.3. There is content in topic A.2 that I want to add as a reference to TOC B, without the rest of those A topics, but A.2 links back to A. So if I want to kill that link, semantically I can't even think of a condition that I would assign at the topic level to topics A, A.1, and A.3 that I would then exclude from target B. But even if I called it "Misc.OnlyA2" and excluded it from target B, I'm pretty sure that Flare would not disable the link from A.2 back to A, at least not in an HTML target.

In any case, it leads to a very hard-to-maintain and semantically confusing project.
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: Non TOC topics appear in Search

Post by NorthEast »

Rona Kwestel wrote:For the current case that raised this issue for me, I ended up pulling in all the related topics in a "Reference" section, but it's not ideal and adds content I didn't need/want in that other target.

Regarding your suggestion, I'm not even sure I understand. I have topic A that links to A.1, A.2, and A.3. There is content in topic A.2 that I want to add as a reference to TOC B, without the rest of those A topics, but A.2 links back to A. So if I want to kill that link, semantically I can't even think of a condition that I would assign at the topic level to topics A, A.1, and A.3 that I would then exclude from target B. But even if I called it "Misc.OnlyA2" and excluded it from target B, I'm pretty sure that Flare would not disable the link from A.2 back to A, at least not in an HTML target.

In any case, it leads to a very hard-to-maintain and semantically confusing project.
My suggestion was to put the condition on the topic, not the links to that topic. You don't need to put conditions on any of the links, because if that topic is excluded from the target using a condition, then Flare will automatically convert links to that topic to plain text (i.e. do the same as an "unbind" on the link). This works for HTML5 and PDF.

So you set a condition on the topics A, A.1, A.3 (i.e. topics that aren't included in target B), and in target B you exclude that condition. In the target B output, links to these topics will automatically be converted to plain text, and links to A.2 will work as normal.
doc_guy
Propellus Maximus
Posts: 1979
Joined: Tue Nov 28, 2006 11:18 am
Location: Crossroads of the West
Contact:

Re: Non TOC topics appear in Search

Post by doc_guy »

Dave Lee wrote:So how do you currently handle xrefs to missing topics in this project, or are they just broken?
They are just broken. Which is lame. But we do have a print condition of text after the topic where we say what guide to look in for that topic. So in online output it would say "For more information see "Widget Preferences." And in PDF output it would say "For more information see "Widget Preferences" in the Administration Guide". In the second case, Widget Preferences is a broken link in the PDF. It's much less than ideal, but we don't have the bandwidth or, frankly, the desire to change it. PDFs are a secondary target type for us. We're required to provide them (for example, for some government contracts), but we expect almost all of our users to be using the online help.
Paul Pehrson
My Blog

Image
Rona Kwestel
Sr. Propeller Head
Posts: 212
Joined: Wed Apr 04, 2007 11:50 am

Re: Non TOC topics appear in Search

Post by Rona Kwestel »

Dave Lee wrote:My suggestion was to put the condition on the topic, not the links to that topic. You don't need to put conditions on any of the links, because if that topic is excluded from the target using a condition, then Flare will automatically convert links to that topic to plain text (i.e. do the same as an "unbind" on the link). This works for HTML5 and PDF.
Thanks, Dave. I understood your suggestion but don't think I realized that those excluded topic-level conditions would force the unbinding behavior for both HTML5 and PDF. It would indeed solve my problem, and I will test it out, assuming I can find some sort of semantically meaningful condition that will make sense to me a year from now, or even a month from now. Mind you, we maintain a "Flare Doc Workflow" topic in Confluence that documents the entire project - variables, conditions, content, targets, ... - including where to find it and how to build/publish from it, for just this reason.
ChoccieMuffin
Senior Propellus Maximus
Posts: 2630
Joined: Wed Apr 14, 2010 8:01 am
Location: Surrey, UK

Re: Non TOC topics appear in Search

Post by ChoccieMuffin »

doc_guy wrote:
Dave Lee wrote:So how do you currently handle xrefs to missing topics in this project, or are they just broken?
They are just broken. Which is lame. But we do have a print condition of text after the topic where we say what guide to look in for that topic. So in online output it would say "For more information see "Widget Preferences." And in PDF output it would say "For more information see "Widget Preferences" in the Administration Guide". In the second case, Widget Preferences is a broken link in the PDF. It's much less than ideal, but we don't have the bandwidth or, frankly, the desire to change it. PDFs are a secondary target type for us. We're required to provide them (for example, for some government contracts), but we expect almost all of our users to be using the online help.
I do something similar, but rather than just adding "in the Administration Guide" conditioned for PDF, I do it like this:

For more information see <condition=OnlineOnly>Widget Preferences</condition><condition=PrintOnly>Widget Preferences in the Administration Guide</condition>.

*** Yes, I know that's not the full way it looks in Flare - I'm not in Flare at the moment but that should give you a bit of an idea.

It's a pain, and less than ideal, but at least you don't have a broken link in your PDF. (Gonna have to give some of the other suggestions a try though...)
Started as a newbie with Flare 6.1, now using Flare 2023.
Report bugs at http://www.madcapsoftware.com/bugs/submit.aspx.
Request features at https://www.madcapsoftware.com/feedback ... quest.aspx
Rona Kwestel
Sr. Propeller Head
Posts: 212
Joined: Wed Apr 04, 2007 11:50 am

Re: Non TOC topics appear in Search

Post by Rona Kwestel »

Choccie, I've done the same thing, and it is a pain, but maybe creating a link snippet for that purpose would work well, where it already has the conditions built in, and then you just update the link and the unlinked text after converting the snippet to text. I store those types of snippets in a folder called "Templates".
Rona Kwestel
Sr. Propeller Head
Posts: 212
Joined: Wed Apr 04, 2007 11:50 am

Re: Non TOC topics appear in Search

Post by Rona Kwestel »

Just reporting back with thanks to Dave Lee's suggestion. It's a bit of a nuisance, but it does the job, and hopefully won't be too onerous to maintain, since I only need to "turn it on" when I know I need it.

For the sake of example, let's say I have a series of topics on fruits that all link to each other in a natural, unforced way, like this:
While oranges are packed with vitamin C, did you know that apples keep the doctor away?"
rather than this:
"See Apples for details on keeping the doctor away."
I created a condition tag set named FruitTopics with the following entries:

Code: Select all

Fruit
Apples
Oranges
Bananas
Pears
And I applied each condition to its corresponding topic in that topic's Properties dialog.

Then in the target that specifies the TOC that only includes the Oranges topic, I exclude all the FruitTopics conditions except for FruitTopics.Oranges, which I leave alone - it will be included by virtue of its presence in the TOC. When I build that target, none of the excluded topics get pulled in, and all the links to them from the Oranges topic are converted to plain text, where they read normally and nobody would be any the wiser that they were once linked.
While oranges are packed with vitamin C, did you know that apples keep the doctor away?"
Hope that helps anyone else in the same predicament.
Rona Kwestel
Sr. Propeller Head
Posts: 212
Joined: Wed Apr 04, 2007 11:50 am

Re: Non TOC topics appear in Search

Post by Rona Kwestel »

Oh, Lord, I just typed an ENTIRE POST with yet a new finding on this vexing issue, and by the time I hit Preview without remembering to copy my text first, it forced me to login again and WIPED OUT EVERYTHING I TYPED!

So now here's the short version. Because maybe this will help someone, and if nothing else, it helps me to get my aggravation off my chest.

It turns out there's an insidious bug related to this issue. When you condition a topic at the file level (which puts the condition on the html tag) and exclude that condition from your target, Flare still traverses the topic and includes any topics that the to-be-excluded-at-the-last-minute topic links to. So while tagging at the topic level provides the benefit of unlinking the links to that excluded topic from other topics included in your target, you further need to tag the content WITHIN the topic to make sure none of its links get picked up, even though logic suggests you would NEVER want to include linked content from a topic you are very specifically excluding in its entirety.

In any case, I discovered that you can apply the condition on the body tag to ensure that any new content added to the topic gets excluded, but you need to do this manually in the Text Editor because the XML Editor doesn't provide the option to set conditions on the body block via the right mouse menu.

I will report this finding back to MadCap on the support ticket I opened after spending the ENTIRE DAY trying to figure this out, and they'll tell me they'll create a bug ticket, and that will be the last I'll ever hear about it. They've got their heads in the cloud pushing auxiliary products instead of fixing the core product right here on the ground.

And now to select all and copy my text before I have to type it in yet again... :roll:
Post Reply