Topics can get incorrectly included in HTML5 output
Posted: Thu Apr 15, 2021 11:33 am
I'd like to make people aware of what I believe to be an extremely serious bug in Flare that results in content (topics) that should be conditioned out being included in HTML5 output.
The "excluded" topics are findable only through search (as well as the topic htm files physically being present in the output if you know the path/filename).
In our case we generate several different web outputs, aimed at difference audiences, from the same Flare project (as there is some shared content), and it is important that there is no bleed of unrequired content from one set of output to the other. This happened to us and we only realised when we noticed that some "wrong" topics were appearing in search results.
Here's how you can make it go wrong:
1. In the HTML5 target - Advanced - set "Content to include" as Content linked directly or indirectly from the target.
2. Create a new topic e.g. newtopic.htm. Do not add it to a ToC.
3. Create a new snippet e.g. linksnippet.flsnp that includes among its content a link (hyperlink or cross reference) to the new topic (newtopic.htm), and then add that snippet to an existing topic that is already included in your target output e.g. existingtopic.htm so as to (correctly, for now) pull in that new topic.
4. Create an "excludeme" condition and apply it to the link in linksnippet. (The condition can be applied directly on the link, or to the paragraph containing the link.)
5. In existingtopic.htm apply a snippet condition to linksnippet to make it exclude the conditioned content (the link to newtopic) in the snippet.
6. Build the target.
7. View the output and from within the existingtopic.htm topic you'll see that the paragraph/hyperlink (that you applied the "excludeme" condition to) is correctly excluded i.e. there is no link to newtopic.htm from existingtopic.htm.
8. However, the newtopic.htm file will have been included in the output (and searching for any content in that topic will find it and list it in the search results).
It's worth noting that if the "excludeme" condition is applied at the target level (rather than within the topic hosting the snippet) then the newtopic.htm file is fully excluded from the output, as expected.
I raised this as a bug with Madcap and they say it is intentional behavior: "The reasoning behind keeping the topic in the output (even though the text containing the link to the topic being removed was successfully conditioned out) is that the snippet and its linked content can be present in the project elsewhere where the paragraph tag and its linked topic would be included intentionally. This functionality is there to prevent breaking other single sourced content."
To me this response is nonsensical. Surely the point when the snippet and the linked content is intentionally used is the time to include that linked topic in the output i.e. don't assume
it might be used elsewhere; it should only include it when it is actually used. My concerns about security and unintentional leaking of sensitive content were disregarded. I assume when people check their output they don't always use search to confirm that content they thought they had excluded is actually being excluded.
If you agree with me and this bothers you then please raise it as a bug with Madcap and hopefully they will change the behaviour of Flare if enough people complain.
The "excluded" topics are findable only through search (as well as the topic htm files physically being present in the output if you know the path/filename).
In our case we generate several different web outputs, aimed at difference audiences, from the same Flare project (as there is some shared content), and it is important that there is no bleed of unrequired content from one set of output to the other. This happened to us and we only realised when we noticed that some "wrong" topics were appearing in search results.
Here's how you can make it go wrong:
1. In the HTML5 target - Advanced - set "Content to include" as Content linked directly or indirectly from the target.
2. Create a new topic e.g. newtopic.htm. Do not add it to a ToC.
3. Create a new snippet e.g. linksnippet.flsnp that includes among its content a link (hyperlink or cross reference) to the new topic (newtopic.htm), and then add that snippet to an existing topic that is already included in your target output e.g. existingtopic.htm so as to (correctly, for now) pull in that new topic.
4. Create an "excludeme" condition and apply it to the link in linksnippet. (The condition can be applied directly on the link, or to the paragraph containing the link.)
5. In existingtopic.htm apply a snippet condition to linksnippet to make it exclude the conditioned content (the link to newtopic) in the snippet.
6. Build the target.
7. View the output and from within the existingtopic.htm topic you'll see that the paragraph/hyperlink (that you applied the "excludeme" condition to) is correctly excluded i.e. there is no link to newtopic.htm from existingtopic.htm.
8. However, the newtopic.htm file will have been included in the output (and searching for any content in that topic will find it and list it in the search results).
It's worth noting that if the "excludeme" condition is applied at the target level (rather than within the topic hosting the snippet) then the newtopic.htm file is fully excluded from the output, as expected.
I raised this as a bug with Madcap and they say it is intentional behavior: "The reasoning behind keeping the topic in the output (even though the text containing the link to the topic being removed was successfully conditioned out) is that the snippet and its linked content can be present in the project elsewhere where the paragraph tag and its linked topic would be included intentionally. This functionality is there to prevent breaking other single sourced content."
To me this response is nonsensical. Surely the point when the snippet and the linked content is intentionally used is the time to include that linked topic in the output i.e. don't assume
it might be used elsewhere; it should only include it when it is actually used. My concerns about security and unintentional leaking of sensitive content were disregarded. I assume when people check their output they don't always use search to confirm that content they thought they had excluded is actually being excluded.
If you agree with me and this bothers you then please raise it as a bug with Madcap and hopefully they will change the behaviour of Flare if enough people complain.