single project > many outputs: xref best practice?

[pdenchfield]

Sometimes writers on our team want to reference a topic in another manual, which helps readers who are viewing a combined online output containing all/most manuals; the reader can simply click the link to find the referenced topic. In Flare we can insert these references easily for most manuals because many are stored in the same Flare project.

However, we also produce single-manual PDF outputs. In these outputs, the references don't work because the topic is omitted from the PDF. So we configured these xrefs to "unbind" for printed outputs so the text would remain but the bad link would go away. This approach works great, except if the heading in the referenced topic contains a variable. In that case, the variable is dropped. "About [ABC Software]" becomes "About."

What is the best practice for inserting xrefs to same-project topics that are in the combined online output but that are also known to be excluded from the smallest level of output (single-manual PDF)?

[forfear]

I tend to try this

I insert x-refs, at the end of paragraphs.

bl bl bl bl. See [xref].

this is the approach i notice that the madcap help author used as well generally. also if the links all occur in one line like in a list

- [link]
- [link]

then all occurrences of [link] could be potential xrefs.

I don't use xrefs exclusively however, flexible as it may be. i try to use hyperlinks on many occasions when i think hyperlinks are more appropriately embedded in a particular active keyword in a sentence. or you can alternately create explore separating xrefs into separate sentences so that About ABC becomes
About ABC. See [xref]

its not odd, i think i've seen this done a lot in the Apple/ Mac OS X/IPOD PDFmanuals.

[pdenchfield]

Thanks for your reply. Hyperlinks do not automatically update with the text of the topic heading, so we have been using cross-references instead.

Since I wrote this query, we came up with a method of doing these cross-references (xrefs). For an xref that points outside the current manual, we mention the subject, the xref'd topic heading, and the manual. Then we tag the xref (and subsequent locator word "in") with a condition tag "XrefOtherManual" so the phrase can be excluded from targets that produce single-manual PDF outputs, resulting in a brief reference of the other manual. We also snippetize the manual name part of the reference and apply mutually exclusive condition tags to alternate phrases for the "manual" (which is merely a "section" in the combined WebHelp output).

Example for combined WebHelp output:
For information on installing the ABC tool, see "Installing the ABC Tool" in the ABC Administrator's Guide section.

Example for single-manual outputs:
For information on installing the ABC tool, see the ABC Administrator's Guide.

Hope this helps others who may have been struggling with similar xref/single-sourcing issues!

[forfear]

The method you mentioned looks pretty sound and solid indeed.

[bobmoon]

We do something similar, since we also generate a combination of web help and stand-alone guides. I've started using snippets as a convenient way of inserting XRefs, since I've found it hard to consistently select the text I want to conditionalize.

For a link to a target that will be in the same PDF, we do this: "... for more information see <Topic> in <Chapter>." I created a snippet where [ in <Chapter>] is conditional to show in print output only.

So I insert the snippet, right click and choose Convert to text, and then I can delete <Topic> and drag and drop the topic from the Content Explorer. Then I delete <Chapter> inside the condition tag (leaving the leading space and "in"), and I drag and drop a print-only topic I created for the chapter TOC page. It has the chapter number and name in the properties.

So the resulting output in PDF looks like this:
...for more information, see Budget Item Measures in Chapter 2, "Working with the Budget".

while the online output looks like this:
...for more information, see Budget Item Measures.

For the few places where we have references to output that ends up in another PDF, we add the guide name to the conditional text. Like this:
...for more information, see Budget Item Measures in Chapter 2, "Working with the Budget" in the Accounts Payable User's Guide.

Bob

[pdenchfield]

Thanks, Bob. For the last case, do you tag or otherwise format the topic xref so no bad links are created in the PDF?

We have decided to tag the topic xref (and its subsequent locator word "in") with a condition, and in the target, if it's not a target that produces content from all manuals, we exclude that condition.