finding broken links in target

[davidfass]

This seems like a really basic thing, but I'm baffled...

How do I find broken links in a particular target? Here's the situation: I have a master TOC with topics A,B,C,D,E. I apply conditions so that Target #1 consists of topics A,B,C. Target #2 consists of topics C,D,E. I want to make sure that when I build Target #1, I do not have links going to topics D or E, because these links will be broken. And when I build Target #2, I want to make sure I do not have links going to topics A or B for the same reason. How do I test this? In other words, how do I test for broken links for a particular target.

The Project Analysis 'Broken Links' does not work because that analyses the whole project, and the links only become broken when I generate the target. So what's the deal here? Thanks for an insight.

[MattyQ]

Hi, David,

We had this same issue. I ended up creating a utility that scans for broken links, images, bookmarks, etc. after a Flare project is generated in order to resolve this issue. However...

An easier way may be to export the project based on the target you're trying to build. Since it will use the target settings to determine what files are exported, the broken links that are in the output should occur in the new project itself. In that exported project, then, you should be able to use the Broken Links analysis.

exportToNewProject.png

[davidfass]

Brilliant!!!! I will try that this afternoon. Thanks so much! -- Dave

[NorthEast]

Would it not be a lot easier to just build the target and check the build log?
The build log will report any links to topics that have been excluded by conditions.

[davidfass]

Well, here's the issue (I think). I have been excluding topics by placing conditions on the TOC. But this means that topics that are LINKED to topics in the TOC are also included in the build. But those LINKED topics are among those I have excluded in the TOC. This means that when someone searches the doc, they get hits for many items that are not in the TOC. So I think I was wrong to say the links are broken. They are not technically broken. But they are links to topics that should not be in the build.

But here's what I am doing now, along the lines of what you are suggesting, I think. I am adding a parallel set of conditions to the actual files (in Content Explorer), in addition to the TOC. This DOES genuinely exclude the files from the build, and creates broken links that are reported in the build log, so that I can then track them down and conditionalize the links. Too much work... hundreds of links to conditionalize... but I think I'm going to get there.

I suggested to Madcap support that this should be automated somehow. For example, if a file is excluded by a condition, all links to that file should be automatically excluded also. (Or at least some option for this should be presented.)

Thanks.

[MattyQ]

David, I'm glad it worked out. That's an age-old limitation of Flare, I feel the same way. Kinda wish it behaved closer to RoboHelp, which had the option to copy any condition tag you applied to the TOC directly to the corresponding topic.

Would it not be a lot easier to just build the target and check the build log?
The build log will report any links to topics that have been excluded by conditions.

While the build log may be easier in the specific case you mention, Dave, exporting the project accounts for more than topics excluded by conditions. Just expanding on this real quick for anyone who searches for broken links on the forums and comes to this thread.

If a project has relative links to other files on the system outside the project, the Broken Links analysis will not identify them, and they won't appear in the build log because the files technically exist where they should be during the build process. Subsequently, of course, the links will be broken as the relative path has changed. This is a mistake I've encountered somewhat commonly with people who like to drag-and-drop to create links in Flare, or who think relative-linking to another Flare project on their file system will work the same way once it's published to the web.

The same behavior is true of links that have been incorrectly copied out of review packages (not uncommon with writers new to using review packages, in my experience), as well, since the URL structure Flare identifies as accurate even if it doesn't work in proper HTML output. If a link to a topic inside a review package is included, it will be broken in the output, but Flare won't identify it. When you go to export a project that includes mczip:// URLs, the export will generally fail, which is a good indicator that you may have those sort of links also.

Project export can be a good acid test for both these issues, as the relative links will be broken in the former case (if the project is unzipped at a different level of the file tree), or won't even successfully complete in the latter case.

A too long example of build log and Broken Links analysis not catching links that WILL be broken but are otherwise valid:

brokenLinksInProjects.png

The error message that can crop up if you try to export a project that includes the review links (URL includes mczip://):

exportError.png

[MattyQ]

Would it not be a lot easier to just build the target and check the build log?
The build log will report any links to topics that have been excluded by conditions.

Also, sorry, honestly not trying to harp on this -- I'd never really tried this method, so was testing it out. I'm not actually seeing any links being reported. Is it one of the warnings you have to enable in the target?

Can you let me know if I'm doing this wrong? I'd like to be able to do some automation based on the behavior you described, Dave, just wanted to make sure I'm testing it right. I included a link in my Leviathan topic to PrideAndPrejudice, and note that Pride and Prejudice is still in my TOC.

targetSettings.png

In the output, the links (because they're to conditionally-excluded topics) are removed, as expected. The log doesn't give me any feedback about that, though, only that one of the topics was excluded from the output:

Code: Select all

Compiling target HTML5...
Removing previously generated content...
Loading skin info...
Gathering Glossary information...
Gathering Auto-index information...
Loading Master TOC...
Processing Master TOC...
Excluded from output:file:///C:/Users/mwilliams/Documents/Working Projects/WebsiteSearch/WebsiteSearch/Content/PrideAndPrejudice.htm.
Generating Glossary...
Collecting source files...
Processing source files...
Processing CSS: Resources\Stylesheets\Modern.css...
Processing CSS: Resources\Stylesheets\Styles.css...
Generating output files...
Processing topic: GreatExpectations.htm...
Generated GreatExpectations.htm
Processing topic: Leviathan.htm...
Generated Leviathan.htm
Processing topic: Frankenstein.htm...
Generated Frankenstein.htm
Generating output skins...
Generating synonyms file...
Generating alias file...
Processing audio links...
Generating final TOC...
Generating concept and keyword anchors in output files...
Generating Index...
Generating Concepts...
Generating Template Topics...
Generating Search.htm...
Topic marked 'not searchable': Search.htm...
Generated Search.htm
Resolving links in output files...
Generating Search Database...
Writing search entry cache...
Generating final output...
Generated Default.htm
Saving result set...
Output generated in 3 second(s).

Done
Saving log to "C:\Users\mwilliams\Documents\Working Projects\WebsiteSearch\WebsiteSearch\Output\mwilliams\HTML5\HTML5.mclog"

[davidfass]

Maybe we are not looking in the same place. I excluded the files that I do not want to be in the build, and then I look at the table of warnings that gets generated when the build finishes (press 'Open Build Log' and select the 'Warnings' tab). If you double-click on a row, it opens the offending file. That's not as helpful as it should be, because the offending file may contain dozens of links, and you have to be a detective to find the one that's actually broken. This is just silly. Flare obviously *knows* where the broken links in the file are, but it's not telling....

I've run into another problem with this broken links list, which I assume is due to some bug, where files that have been excluded from the build (both the topic and TOC entry) still appear as reporting broken links. How can a file that's excluded from the build be reported as having broken links? Then, if I rebuild the project some time later, these items disappear. Who has patience for this stuff? I don't know.

[Psider]

David, I'm glad it worked out. That's an age-old limitation of Flare, I feel the same way. Kinda wish it behaved closer to RoboHelp, which had the option to copy any condition tag you applied to the TOC directly to the corresponding topic.

Slightly off topic, but where would I find this Robohelp option you mention?

Thanks in advance

[MattyQ]

I've run into another problem with this broken links list, which I assume is due to some bug, where files that have been excluded from the build (both the topic and TOC entry) still appear as reporting broken links. How can a file that's excluded from the build be reported as having broken links? Then, if I rebuild the project some time later, these items disappear. Who has patience for this stuff? I don't know.

I've run into issues like that where the culprit was the Analyzer folder in the Flare project folder. I can't say that deleting the Analyzer folder fixed the problem permanently, but it seemed to help for awhile.

Slightly off topic, but where would I find this Robohelp option you mention?

Worked up a quick screenshot to show it, since I forget my RoboHelp lingo. We refer to these things as "pods", is that right? In any case... EDIT: I realize the screenshot doesn't show it. Where I've right-clicked to get the menu, that's in the Table of Contents, on the topic(s) that I want to add condition tags to.

applyTagsAtSameTime.png

[Psider]

Oh my god! That is amazing! Thanks @MattyQ!

(Apologies to all for hijacking the thread. Back to the regularly scheduled program now. )