Text Insets and Conditional Text
For FrameMaker users seeking single sourcing on a shoestring, Tammy Van Boening of Spectrum Writing offers a solution based on these features.
[EXCERPT FROM THE AUTUMN 2009 ISSUE OF COMMUNICATOR MAGAZINE]
Text insets in FrameMaker offer a way to single-source content by sharing chunks of text across multiple files and books. Text insets are FrameMaker files that you import by reference into another FrameMaker file. The terms used to describe the files used are:
- Container file (destination file) — this is the FrameMaker file into which you import one or more text insets. This is also the file you use to build the book you are creating.
- Text inset (source file) — this is the FrameMaker file that you import into the container file. It typically contains content that you want to share across multiple files or books.
Figure 1 shows examples of both types of files.
Using Text Inset Files
You can put each piece of text into a separate file or place them in separate flows of a single file. You also have options when you import the text inset. Below are tips for setting up text inset files:
- To ensure that all styles, conditions and variables have the same names, use the same template as you use for container files.
- Name files carefully to make their contents easily identifiable. For example, you could base the names on the headings that the text inset goes with and end them with an identifying suffix:
- Intro suffix for introductory text.
- Overview suffix for conceptual or explanatory material.
- Proc suffix for procedures.
- Text insets inherit the conditional text settings of the container file. Use conditions as necessary in the text inset files (Figures 2 to 4).
- If you need a whole text inset to be set up with a condition, apply the condition in the text inset file to all of the text. If you apply the condition to the whole text inset in the container file, you will lose the condition setting when you update the text inset.
- You cannot use conditions on individual rows of a table that is in a text inset file. You can, however, use conditions on an entire table in a text inset.
- Import variables into the text inset file: importing variables into the container file does not change them in the text insets.
- Make the first paragraph of each text inset file a small anchor tag and put a non-breaking space as the first character in the paragraph (Figure 5).
- All headings, figure captions and table titles are in the container book’s TOC, LOF and LOT, whether the heading, figure caption, or table title is in a container or a text inset file.
- All auto-numbered items such as figures and tables will be numbered correctly, whether the item is in a container file or a text inset file.
- Place all text inset files into a separate book. This permits:
- Spell checking of all text insets: FrameMaker’s spell checker skips the text insets in the container file.
- Searching and replacing in all text insets: FrameMaker’s search function skips the text insets in the container file.
- Any other book-level functions, such as show/hide conditions or importing variables.
TIPS FOR USING FLOWS
- Follow all of the tips above for separate files.
- Name each flow carefully to make the flow content identifiable.
- Consider using flows for all insets for a particular chapter, so that each chapter has a single text inset file, with a separate flow for each text inset.
To Create a Text Inset:
- Create a new, empty file based on your chapter template.
Note: Make sure the file has all of the variables and conditions you need to use.
- Apply your anchor style to the first paragraph and put a non-breaking space as the first character in that paragraph (Figure 5).
- Start text in a new paragraph below the one you just created.
- Save the file to the folder where all the text insets for the book will be, giving the file a meaningful name.
- Add all text, tables, and figures as you normally would.
- Make sure that your text ends at the end of flow symbol and that there is no extra paragraph below your text (Figure 6).
- If you need to create cross-references to or from the text inset file, see Cross-references and hypertext markers later in this article.
- Add the file to the text inset book that is in the same folder as the text inset.
- Run the spell check on the text inset book and other book-level functions as needed.
Setting Up Container Files and Importing Text Insets:
Below are some tips for setting up container files:
- Place all headings in the container file. This makes it possible to use normal FrameMaker cross references to all headings, set up index markers and so on.
- Import each text inset file into a small anchor paragraph in the container file. (This is the same anchor paragraph tag that you used for your text insets; however, you do not need a non-breaking space before this tag in your container files.)
- Place index markers in the heading paragraphs of the container files.
- You can open a text inset after you insert it into the container file by double-clicking on any text in the text inset. The text inset does not open if you double-click a graphic in the text inset.
RECOMMENDED OPTIONS FOR IMPORTING TEXT INSETS
Various options are available for importing text insets. However, the default settings (Figure 7) typically meet most users’ needs and require no modification.
MOVING OR RENAMING CONTAINER FILES
If you need to move a container file from one folder to another or rename the file, open the container file and use File > Save As to move it to a new folder or to rename it. This method retains the following:
- Links to text insets
- Links to graphics in both the container file and any text insets
- Links to cross-referenced files that are in their original locations.
If you move the cross-referenced container files, the cross-references break. You can use FrameScript and a custom script to resolve this issue. Framescript is a high level, user-oriented, scripting (or macro) language designed to work with Adobe FrameMaker. You use FrameScript to customize the features of your FrameMaker installation. In this customization, a custom script can look for the referenced files in the same folder as the container file and update the path to the cross-referenced file. Visit www.framescript.com and www.frameexpert.com for FrameScript and the necessary custom scripts, respectively.
To Create a Container File
- Create a new, empty file based on your chapter template.
- Enter all headings needed in the document.
- After each heading, press Enter to create a new, empty paragraph.
- Apply your anchor style to the paragraph that you have just created.
- With the cursor in the empty paragraph, select File > Import > File to open the Import dialog box.
- Select the text inset file you want to import. Leave the Import by Reference option (the default) selected.
- Click Import to open the Import Text Flow by Reference dialog box.
- Select the options you need. Leave the default options selected, as shown in Recommended options for importing text insets, as these work well.
- Click Import.
- Save the file.
- Continue adding headings and text insets as necessary.
- Add index markers to the heading paragraphs.
- If you need to create cross-references to or from the container file, use standard FrameMaker procedures for creating cross-references.
- If you make changes to a text inset, you must do one of the following to ensure that the container file has the latest version:
- After closing the text inset, double-click the text inset and click Update Now.
- From the container file, select Edit > Update References, select the two text inset options and click Update.
- Update the book.
To Use a Container File in a Book
- Open the book in which you want to use the container file.
- Add the container file to the book just as you would add any other file.
- Update the book, making sure that the Update All Text Insets option is selected.
If necessary, before step 3:
- Spell check your separate text inset book.
- Carry out any search and replace operations on both the book file and the text inset book file.
Cross-References and Hypertext Markers
Cross-references and text insets are a complex subject. You can manually create the necessary references and markers; however, custom FrameScript scripts can easily resolve these issues for a fraction of the cost and time of manually resolving them. Visit www.framescript.com and www.frameexpert.com for FrameScript and the necessary custom scripts, respectively.
Text insets and generated files
The numbering and content in index markers, headings, tables and figure captions you create in text inset files will be picked up by any generated files in the book containing container files. This means that your table of contents (TOC), list of figures (LOF), list of tables (LOT) and index files include all the paragraph tags that you expect them to from both the container files and the text inset files used in your container book.
JUMPING FROM THE TOC, LOT OR LOT
If you try to jump to a specific item that is in a text inset file in FrameMaker using Ctrl+Alt+Click, for example to a figure from the list of figures, the container file opens and the whole text inset where the figure appears is selected but does not open. However, after you create a PDF file and click a paragraph in the LOF, you will go directly to the figure.
JUMPING FROM THE INDEX
If you try to jump from the index file in FrameMaker to an index marker in a text inset file using Ctrl+Alt+Click, the text inset file opens and the index marker is selected. This behavior is completely normal. If you edit the index marker, close the text inset file and update the container book, then your index is updated.
This article has shown that by using FrameMaker, FrameScript, text insets and conditional text, those who do not have the budget, time or personnel to implement new tools can share chunks of content across multiple books.
Tammy L. Van Boening is an STC Senior Member and an officer in the Rocky Mountain Chapter. She has strong experience in devising inexpensive single-sourcing techniques for small technical writing and training departments since 2000. Tammy specializes in creating usable documentation for software products for both print and online use and has developed and delivered writing and training products for a diverse range of industries and clients.