TOC requirement for PDF

[paul55]

Hi,

This may have been asked before, but in searching around all day I couldn't find it...

It appears that if a project has a cross-reference or hyperlink to a topic that isn't present in the TOC for the PDF target, then the hyperlink won't work and things like page numbers won't get expanded (if using an xref style that includes those). That makes sense, but why isn't this considered an error when building the project? I banged my head against the wall for hours trying to find a couple problems with links, only to discover that whoops -- I'd forgotten to add the target topics to the TOC. Dumb mistake, I know, but having this reported at compile time would have saved a lot of time.

Maybe this was done by design, in order to support cross-PDF-file links maybe? I'm not using anything like that, so at least having an option to turn these cases into errors would be very helpful. Should I make a feature request?

HTML Help and WebHelp outputs don't seem to have this issue -- instead, they seem to automatically include linked topics, even though they don't appear in the TOC assigned to those targets. These targets don't produce any errors or warnings about the missing topic link either. Is this by design also?

(Edit -- I'm using Flare v7.1, in case that matters.)

Thanks,

-Paul

[LTinker68]

Online outputs automatically include all topics, regardless if they're in the TOC Editor or not, unless they're excluded using conditions at the topic level. If you exclude them in the TOC Editor then you're just excluding that TOC entry from the navigation pane in online output -- the topic itself is still in the output.

Print outputs only include the topics that have been added to the TOC Editor.

Some people use one TOC for both output types and condition out topics in the TOC Editor that shouldn't appear in print output. Other users have two TOCs -- one for online outputs and one for print outputs. The advantage of the latter setup is that you don't have to remember to condition out a topic in the TOC if you don't want it in the print output. The downside is that if you do want a topic in both outputs, you have to add it to both TOC files, assuming you want that topic to appear in the online TOC (if it's not added to the online TOC it will still be in the output, it just won't appear in the navigation pane).

[Nita Beck]

One of my best practices for PDF output is, after generating the PDF, to search within it for "page 1." It's rare that I cross-reference to a topic that appears on the first page (say the first page of Chapter 1) in a print doc, so usually if I get any hits for "page 1," that's a dead cross-reference because the destination topic isn't present.

[paul55]

Hi, sorry for the late reply & thanks for your responses. Lisa, your idea of having a single TOC might make more sense, since at this point I think that most if not all of the new content I'll be creating, will need to go into both the online and PDF outputs. Then I'll just condition out the few topics I don't want in one or the other output.

Nita, your suggestion is a good one & I'll try that too. I guess I still don't see *why* the different outputs work this way though. I can see why print outputs won't automatically include linked topics, since Flare wouldn't know at what location to include them in the output -- that part makes sense. But if I have a link to a topic that's not in the TOC, it's necessarily going to generate a dead cross-reference, right? So shouldn't that be considered an error?

Thanks,

-Paul

[Nita Beck]

But if I have a link to a topic that's not in the TOC, it's necessarily going to generate a dead cross-reference, right? So shouldn't that be considered an error?

I completely agree. Flare should recognize it as an error for that particular target. Right now, Flare is programmed only to check for broken links within a project at large, not on a per-target basis. Many of us have submitted feature requests for a by-target check. The more requests MadCap receives for this feature, the more likely we are to get it at some point. Here's where you can put in a feature request: https://www.madcapsoftware.com/bugs/submit.aspx

[helen]

One of my best practices for PDF output is, after generating the PDF, to search within it for "page 1." It's rare that I cross-reference to a topic that appears on the first page (say the first page of Chapter 1) in a print doc, so usually if I get any hits for "page 1," that's a dead cross-reference because the destination topic isn't present.

Absolutely - this is what I do too. It would be nice to have it flagged at compile time, however.