cross references in topics used as text insets

[Combs, Richard]

Eaton, Doug wrote:
 
> Hoping to realize some efficiencies through the reuse of 
> content, we are considering how to disassemble content in 
> legacy documents into separate topics that will be inserted 
> as needed into container documents. There will be three kinds 
> of cross references in these documents: Topic to Topic, Topic 
> to Container, and Container to Topic. <snip> 
> 
> The deliverables will be PDFs with (we hope) working links.
> 
> What is the best practice for achieving this using 
> unstructured FrameMaker? Will moving to structured FrameMaker 
> make this effort any easier?

There are two overall issues with cross-references and text insets: 

1) Making the xrefs work in FM, i.e., resolve. Keith Arnett had some
good advice on that. But let me re-emphasize something he said, but
didn't dwell on. To set up an xref to a location outside the text inset
(either to another text inset or to the container, you _first_ create a
cross-reference marker at the destination/target (Special > Marker,
Marker Type: Cross-Ref, Marker Text: something meaningful that
identifies this location). 

If this target you just inserted is in a text inset, you need to update
it in its container (so the container "knows" about the new marker).
Then, when you select Special > Cross-Reference to insert the xref, set
Document to the _container_ doc in which the text inset with the target
marker resides, and set Source Type to Cross-Reference Markers. In the
list of markers, find that meaningful marker text you entered for the
target marker. 

If you're conscientious and disciplined about inserting the target
markers first and then pointing xrefs to them in the _container_ doc(s),
and if you follow Keith's advice about conditionalizing if multiple
destinations are necessary, your xrefs will all work in FM.

2) Making the xrefs work in PDF. Xrefs within a text inset are not
converted into live links in PDF. This is a long-standing bug that,
AFAIK, still hasn't been fixed in FM8. The workaround that some of us
use is to produce a PDF as follows: 

(a) Open all files in the book, update the book, and save all files. 
(b) "Flatten" all the text insets, that is, convert them all to text. 
(c) Save as (or print to) PDF. 
(d) Close all the files _without_saving_. 

Obviously, step 4 is critical. Step 2 is tedious if you have many
insets. You can eliminate both the tedium and the risk of error by
scripting the whole process (e.g., FrameScript or FrameAC).

IMO, this is the best way to handle the problem. 
 
> On 3 March, Rene Stephenson wrote, "the sure-fire way to 
> handle xrefs in a text inset is actually by using hypertext 
> links rather than xrefs."

Rene's suggestion of using hypertext links is OK for a few links that
are pretty stable. But it doesn't scale well and quickly becomes a
maintenance issue (since you have to manually update the "hotspot" text
when the target changes in a way that obsoletes the link text). 

> One challenge I have with this is in creating the GOTOLINK spot. 
> 
> For example, we currently identify graphics with the chapnum 
> and the figure number followed by a text label. Is the best 
> way to create a hypertext link to insert the XREF to the 
> figure name (no numerals--I'm guessing that they won't 
> necessarily update properly in the container doc), convert 
> that XREF to text, mark the converted XREF with a character 
> tag, and then insert the GOTOLINK command? (Whew! I can 
> almost hear the gnashing of teeth.)

I don't understand your description of the process, and I think maybe
you're confused about how to make hyperlinks. As with creating xrefs to
markers instead of paragraphs, it's a two-step process: 

(1) At the target/destination, insert a "Specify Named Destination"
Hypertext command (i.e., newlink) with a meaningful linkname. 
(2) At the spot you want a link, insert the text to link, format it as a
link (with appropriate char tag), and insert a "Jump to Named
Destination" Hypertext command (i.e., gotolink) that specifies the
linkname you gave to the target's newlink.

There's no reason to insert an xref and convert it to text -- you can
type "See Figure 7-3, 'Configuration Parameters'" faster than you can go
the xref route. 

In any case, the text that you use for the hypertext link -- whether
typed or inserted by your roundabout process -- is static. If the target
changes, the link text doen't update to match, as it does with xrefs.
This is the maintenance issue I mentioned. 

You can minimize maintenance by not including pgf numbers (as you
suggested) or page numbers in your link text (and by consciously
avoiding rewording headings/captions). But this makes the links
essentially useless to someone reading hard copy. And you'll still have
problems keeping the links in sync with their targets.

All in all, I prefer cross-references and the workaround I described
above. 
 
> I realize that this is a complex issue (even putting aside 
> the issue of whether it is safer to put headings... also 
> numbered...in the topics or in the container docs). Can 
> anyone can recommend resources for resolving this issue?

I suggest putting all the headings into the containers and inserting the
text insets below them. That simplifies many things, including the topic
xrefs (generally to headings) and index markers (generally in headings).
Plus, you're less likely complain that the pgf after your text inset
turns into a Heading 1 or something, an issue that seems to come up
every 4-6 weeks. :-)

That's my ... oh, about six or eight cents, I'd say. :-) 

YMMV. HTH!

Richard


------
Richard G. Combs
Senior Technical Writer
Polycom, Inc.
richardDOTcombs AT polycomDOTcom
303-223-5111
------
rgcombs AT gmailDOTcom
303-777-0436
------