Adding links to topics/bookmarks in other projects

[adelleolson]

I am converting from FrameMaker to Flare. With FrameMaker, I created 3 PDF's per product (release notes, getting started, user's manual). I have several products, each with these 3 types of documents. These product docs don't share content, but they do make references to each other. For example, Product A's user's manual might say "see Section XXX in Product B's getting started guide).
Or Product A's user's manual might say "see Section XXX in the release notes" (meaning A's release notes).

I need to have PDF and HTML output for each document.

Should I have:
(1) 1 project per product, and somehow (how?) that project can be set up to build all 3 docs in both PDF/HTML?
or (2) 1 project for each separate doc?

And then, for either method, how can I create links between the docs for Product A and Product B?

Is there a PDF Guide that explains all of this?

[kwag_myers]

I recommend option 2. Flare has a sweet feature that allows you to put separate projects together as it's own project. Take a look at the Global Project Linking Guide.

[Nita Beck]

I don't agree with having one project per each separate document or output. Rather, I think it makes sense to have one project per product. That way, product-specific content that is developed for one kind of output can easily be extended to support another kind of output.

[kwag_myers]

Doesn't that require Conditional Tagging for each output?

[adelleolson]

But is't the "Global Project Linking" guide more about reusing the same content in multiple documents? That's not really what I need. I just want cross-references between documents.

I am leaning towards 1 project per product. But I don't know how to:
1: Use 1 project to create 3 different documents. I'll need 3 different TOCs.
2: Create a link from Product A User's Manual to Product B's Getting Started Guide.

[ChoccieMuffin]

Doesn't that require Conditional Tagging for each output?

Perhaps, but what's the problem with that? It makes the tool very flexible and powerful. And once you've got your head round conditions you'll wonder how you ever managed without them.

[ChoccieMuffin]

But is't the "Global Project Linking" guide more about reusing the same content in multiple documents? That's not really what I need. I just want cross-references between documents.

I am leaning towards 1 project per product. But I don't know how to:
1: Use 1 project to create 3 different documents. I'll need 3 different TOCs.
2: Create a link from Product A User's Manual to Product B's Getting Started Guide.

What you need is 1 target per output. As for TOCs, you can decide to have separate TOCs for PDF and Help or you can use the same TOC if you want the same or mostly similar content, though I notice you are just producing PDFs.

You might need to take care with your cross-references, as if you refer to a topic that is not in the TOC you're using, the cross-ref won't work. You may find you just have to type those names in manually (but I suspect you have to do that already with FrameMaker).

[dorcutt]

What I do for cross references for partial PDFs is I created two condition sets: "Doc Type" and "Not Doc Type." So, I have a Main Manual, and it has its own "Doc Type.Main Manual" condition and a "Not Doc Type.Not Main Manual" condition created for it. Every other document that I produce has its own similar setup: "Doc Type.Small Guide A" and "Not Doc Type.Not Small Guide A". For every target, one "Not Doc Type" is excluded (the one for that target), and all but one "Doc Type" condition is excluded. I also have a variable called "Full Manual Name" that contains the name of the full manual version from the perspective of that small guide. In our example, "FullManualName" is set to "Main Manual."

When I build a smaller PDF guide, I let it run the first time and then see what warnings for bad links I get. I then condition each busted link with "Not Doc Type.Not Small Guide A" and immediately after it add in the phrase "the full <FullManualName Variable>", and condition that "Doc Type.Small Guide A." Lastly, I then set up the Small Guide A target to Exclude "Not Doc Type. Not Small Guide A." and to not include or exclude "Doc Type.Small Guide A." All other "Doc Type" variables are excluded.

This way, my users see the full cross reference everywhere but in the guide that doesn't include that topic, where they see instructions to refer to the full user manual instead. Online output excludes all Doc Type variables.

Works well, even for content shared by multiple small guides. the same cross reference can be kept and conditioned with each "Not Doc Type" condition. The only quirky thing is I need a separate "the full <FullManualName Variable>" phrase for each Doc Type that doesn't include that article. So, in the Flare XML editor, you'd see something like "see Exercise 1.1 Blah""the full <FullManualName Variable>""the full <FullManualName Variable>" if there were two Small Guides that didn't include exercise 1.1.

In any case, it works great for me for many small guides and HTML5 output.

Edit: I accidentally wrote "variable set" instead of "condition set" in the first sentence. I'm sure that didn't help anything.

[kwag_myers]

Doesn't that require Conditional Tagging for each output?

Perhaps, but what's the problem with that?

Nothing. Just seems like a lot of work for something that's already tagged, in a sense. As I see it, you're proposing that the OP puts projects together, then separates them with Conditional tags.

But is't the "Global Project Linking" guide more about reusing the same content in multiple documents?

I've used it the other way around, using multiple documents for a master (global) project. In the second step of the Import Flare Project Wizard, there is an option, Auto-reimport before "Generate Output". If you use the master project for output only, the topics for each output are automatically updated. The only real work you have to do is put the TOCs together. Any changes in the source projects must be done manually in the master project (unless there's a better way I'm not aware of). Just be sure not to import any files that are not topic related, such as FLTOC files.

[adelleolson]

Hmm... the post about "Doc Type" and "Not Doc Type" left my head spinning... I'm new and don't understand most of that.

But I've made some progress. Here's where I'm at now: I know how to add a hyperlink to an external file or website. In Product A's manual, I have a link to a topic in Product B's manual. That works and the topic in B's manual opens in a new window. So far so good! But then that new window for Product B only shows that 1 topic -- no way to navigate around the rest of Product B's manual. Is there a way to fix that?
In the new window for Product B, there's a link at the top: "open topic with navigation", which opens the left-side pane of navigation for Product A's manual. But I want it to be Product B's manual.

[wclass]

I'd set up projects per product, which sounds like what you have done.
To create links between separate webhelp outputs, we set up context sensitive help (CSH) in each. When you link from Product A to a topic in Product B, you make a CSH call - basically, the URL with a "#topic_name" at the end. You can choose to open the help for Product B in a separate window.

EDIT: meant to add, we keep all our help files in the one area, and so we can put in relative CSH calls to other products.

[adelleolson]

Thanks for the ideas, Margaret! However My output isn't Webhelp, just PDF and HTML5.
I am able to get the link to open a new window with the topic from Product B. The problem is that at the top of that window, it has a confusing link "open topic with navigation", which opens the left-side pane of navigation for Product A's manual. Since this window is showing a topic in B, I find that confusing. I expected it to show me navigation for B, not A.

[wclass]

Sorry, I was using "webhelp" generically - CSH works in HTML5 (that is what we use here).

[dorcutt]

Hrm, sorry about the spinning head adelleolson! It's definitely an advanced concept and I should have started off simpler, in retrospect. I was acting like one of my SMEs!

Anyway, in other words, what I do is I use the Flare feature called "conditions" to remove the broken links that happen when the linked topic isn't included. Instead, I "condition" in a placeholder phrase that says "see the main manual" instead of the broken link.

So, here's an example. The topic that I wrote for my main manual has a cross-reference that says, "See Article A" However, when I make a specialized guide about one subject, "Article A" isn't included. If I built my specialized guide with that cross-reference in it, the link would be broken and create a warning. Instead, I use conditions to replace the would-be-broken link so that my topic now says "See the main manual" instead.

The rest of the post was just me going into far too much detail about how I go about doing that.

[adelleolson]

Thanks for simplifying! So in your case, there's no way for you to have a link that goes to that main manual?

[dorcutt]

Yes, there is a link to the main manual, but only where it would work/make sense (the Web format and the Main User Manual print document). In the specialized print version of the document, the link can't possibly work because the article isn't a part of the document.

So, say you are making a help page about a zoo, for some reason. The Zoo User Manual is the full print document, and the main web page is called Zoo WebHelp. Now, you write an article on Zebras for the Zoo User Manual and the Zoo WebHelp, and it includes a phrase that says "Zebras are preyed upon by Lions" and there is a cross-reference to the Lions article. In both the Zoo User Manual and the Zoo WebHelp, the link works fine. Everything is great.

A little while later, your boss tells you that you need to create a Zebra Guide PDF that just deals with Zebra care and maintenance, so you create a new Zebra Guide target and drop some articles related to Zebra care and maintenance into the Table of Contents. Since there are no lions in their cage, the Lions topic is not relevant and it is not included in the guide. Unfortunately, this means that when you go to build your new Zebra Guide, you have a broken link to Lions in the Zebra topic and you get a warning when the target builds.

In this example, my solution is to find the link to the Lions article and then give it a "Not Zebra Guide" condition. I then set the Zebra Guide target to Exclude anything conditioned as "Not Zebra Guide," because it should not be in that target. The Zoo User Manual and Zoo WebHelp targets do not have any setting at all for the "Not Zebra Guide" condition, which means that it is included in the output by default.

That way, the following happens:

• The Zoo User Manual PDF has a working link to the Lions section of the document
• The Zoo WebHelp and has a working link to the Lions article
• The Zebra Guide leaves the sentence out entirely, because it would be broken if it was included.

What I had also done was I took it a step further and swapped in a bit of replacement text for the sentence that was omitted in the Zebra Guide. I write an alternate sentence, such as "Zebras are preyed upon by Lions. For more information about Lions, see the full Zoo User Manual or the Zoo WebHelp." I then flag this as the "Zebra Guide Only" condition, and set up all other targets to Exclude that condition. That way, it only appears in the one Zebra Guide where it is needed to replace the sentence with the broken link.

Does this make a bit more sense with some context? The technique is a bit more complicated, but it allows you to single-source your documents fully. You get a working link where you need it, and you get a sensible replacement text where you need that.

PS: The one drawback I've found so far is that setting up the other targets to Exclude the "Zebra Guide Only" type conditions can get bothersome if you have a large number of targets. There is a way of doing this by using the built-in Find and Replace function of Flare. If you're interested, let me know and I can explain how that works.

[dorcutt]

Thanks for the ideas, Margaret! However My output isn't Webhelp, just PDF and HTML5.
I am able to get the link to open a new window with the topic from Product B. The problem is that at the top of that window, it has a confusing link "open topic with navigation", which opens the left-side pane of navigation for Product A's manual. Since this window is showing a topic in B, I find that confusing. I expected it to show me navigation for B, not A.

I'm not sure (I don't do this in my own webhelps currently) but I think you can link to the other webpage with an external hyperlink to avoid this issue. It looks like they even have your exact situation of linking between two of your HTML5 help pages as their example.

For TOCs, I combine my TOCs where it makes sense (the main PDF and main HTML5 TOCs are one file) and use separate TOCs in other cases. You'll get a sense for where the sweet spot is as you use the program more.

[ChoccieMuffin]

@dorcutt, that's exactly what I do in my Zoo Guide! Excellent description!

One point I would add is that you have to be careful with spacing around your conditioned text.