cross references in topics used as text insets

[Arnett, Keith]

Hi Doug,

I can't speak to structured FrameMaker, but I have been using text
insets in unstructured FM for many years. Effective use of
cross-references isn't rocket science, but it does take a reasonable
amount of planning, care, and consistency of use.

Essentially, there are only two kinds of cross-references in a text
inset: 1) those that point to a location in the same text inset, and 2)
those that point to a location outside the text reference. 

Setting up #1 type x-refs is straightforward and follows the standard
procedure. When setting up #2, the key point to remember is that you
must *always* configure the x-ref to point to a cross-reference marker
in the target container file. As a general rule, you never create
cross-references directly from one text inset file to another.

For example, this means that if your text inset is used in both Doc1.fm
and Doc2.fm, and you want to create a cross-reference that points to the
Glossary at the end of each file, you will need two x-refs in your text
inset -- one that points to the Glossary x-ref marker in Doc1.fm, and
one that points to the Glossary x-ref marker in Doc2.fm. 

Which leads to the application of conditional text tags. More than
likely you will not want both x-refs to appear in both places, so you
will need to create two condition tags and apply them appropriately in
your text inset. Then you must configure your container documents to
show the desired condition tag and hide the inappropriate one.

Successful management of cross-references rests on the consistent
application and tracking of these basic items. Problems creep in when
you accidentally set up a cross-reference to point to a marker that
appears to be correct, but actually resides in a different target
location, or through the misapplication of conditional text tags or
Hide/Show settings.

Obviously there are a lot of other considerations in implementing shared
content with text insets in unstructured FM. Please feel free to contact
me offline if you would like to discuss this in more detail.

Regards,

Keith

--------------------------------------------
Keith Arnett
Doc Team Lead - BPM 
Software AG USA, Inc. \ Fairfax VA
703-460-5927
Mobile: 571-226-0430

-----Original Message-----

Date: Wed, 12 Mar 2008 14:59:26 -0400
From: "Eaton, Doug" <Doug.Eaton at Sensis.com>
Subject: cross references in topics used as text insets
To: <framers at lists.frameusers.com>

Using FrameMaker 8 (unstructured). No FrameScript. No content-management
system.

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. We will want to set
up XREFs to heading numbers, table numbers, figure numbers, and,
probably, page numbers, all of which use a two-level (for example,
"Figure 1-1. A Picture") format.

In addition, all graphics are imported by reference into the individual
topic documents. 

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?

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."
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 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?

Doug Eaton