cross references in topics used as text insets
Hi Doug, Just to clarify, there is a way to make cross-references in text insets work in the resulting PDF file. It can be done with an inexpensive FrameScript script. Contact me offlist if you are interested. Rick Quatro Carmen Publishing 585-659-8267 www.frameexpert.com
cross references in topics used as text insets
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" Subject: cross references in topics used as text insets To: 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
cross references in topics used as text insets
> a location outside the text inset (either to another text > inset or to the container, you _first_ create a Note to self: A comma is not an adequate replacement for a close parenthesis. Make that: "(either to another text inset or to the container)," Richard -- Richard G. Combs Senior Technical Writer Polycom, Inc. richardDOTcombs AT polycomDOTcom 303-223-5111 -- rgcombs AT gmailDOTcom 303-777-0436 --
cross references in topics used as text insets
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. > > 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..
Re: cross references in topics used as text insets
Hi Doug, Just to clarify, there is a way to make cross-references in text insets work in the resulting PDF file. It can be done with an inexpensive FrameScript script. Contact me offlist if you are interested. Rick Quatro Carmen Publishing 585-659-8267 www.frameexpert.com ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
RE: cross references in topics used as text insets
> a location outside the text inset (either to another text > inset or to the container, you _first_ create a Note to self: A comma is not an adequate replacement for a close parenthesis. Make that: "(either to another text inset or to the container)," Richard -- Richard G. Combs Senior Technical Writer Polycom, Inc. richardDOTcombs AT polycomDOTcom 303-223-5111 -- rgcombs AT gmailDOTcom 303-777-0436 -- ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
RE: cross references in topics used as text insets
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. > > 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 heading
RE: cross references in topics used as text insets
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" <[EMAIL PROTECTED]> Subject: cross references in topics used as text insets To: 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 ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
cross references in topics used as text insets
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 ___ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
cross references in topics used as text insets
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
