Framemaker for Single Sourcing

by tammyvb on October 28, 2011

[Excerpt from the Autumn 2009 issue of Communicator Magazine]
Communicator Magazine

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.

Figures 1 & 2

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:

General Tips
  • 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:
    • Figures 3 & 4 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 necessaryin 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.

Figure 5.

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:

  1. 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.
  2. Apply your anchor style to the first paragraph and put a non-breaking space as the first character in that paragraph (Figure 5).
  3. Start text in a new paragraph below the one you just created.
  4. Save the file to the folder where all the text insets for the book will be, giving the file a meaningful name.
  5. Add all text, tables and figures as you normally would.
  6. Make sure that your text ends at the end of flow symbol and that there is no extra paragraph below your text (Figure 6).
  7. If you need to create cross-references to or from the text inset file, see Cross-references and hypertext markers later in this article.
  8. Add the file to the text inset book that is in the same folder as the text inset.
  9. 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.

Figures 6 and 7

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 customise the features of your FrameMaker installation. In this customisation, 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

  1. Create a new, empty file based on your chapter template.
  2. Enter all headings needed in the document.
  3. After each heading, press Enter to create a new, empty paragraph.
  4. Apply your anchor style to the paragraph that you have just created.
  5. With the cursor in the empty paragraph, select File > Import > File to open the Import dialog box.
  6. Select the text inset file you want to import. Leave the Import by Reference option (the default) selected.
  7. Click Import to open the Import Text Flow by Reference dialog box.
  8. Select the options you need. Leave the default options selected, as shown in Recommended options for importing text insets, as these work well.
  9. Click Import.
  10. Save the file.
  11. Continue adding headings and text insets as necessary.
  12. Add index markers to the heading paragraphs.
  13. If you need to create cross-references to or from the container file, use standard FrameMaker procedures for creating cross-references.
  14. 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

  1. Open the book in which you want to use the container file.
  2. Add the container file to the book just as you would add any other file.
  3. 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.

Summary

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 specialises 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.

E-mail: info@spectrumwritingllc.com
Website: www.spectrumwritingllc.com

 

{ 0 comments }

Autonumbering in Microsoft Word

by tammyvb on October 27, 2011

For my technical publications clients, I use a true desktop Publisher (Framemaker) to produce standalone documentation or to single source to an Online Help standard output such as Microsoft HTML 1.x help; however, many of my clients, for their own internal documentation, use Microsoft Word. Because I am a writer, they naturally assume that I know many things about many different tools, and reach out to me for help, in particular, Microsoft Word and numbering. I could write pages and pages about all the issues with numbering Microsoft Word, and I know that we all have felt the pain of opening a document having all the numbering and bulleted lists go to heck in a hand basket for no apparent reason other than “it’s what MS Word does.”

Sequence fields are a way of semi-automating the process of numbering in an MS Word document, and ensuring that you will have stable numbering and bulleted lists in MS Word documents that you produce. It also allows for easy updates of numbering when you insert or delete a paragraph in an MS Word document. I have offered this solution to many of my clients who have suffered the follies of numbering in MS Word and all have been happy and appreciative of the solution. I thought I would make it general knowledge and share it with anyone who chooses to read by blog. Hopefully, this will help alleviate some (but not all) of the suffering when working with an MS Word document.

P.S. This is written from the perspective of Word 2007, so some of the options might be found in different places and/or on different menus in different versions of Word, but once located, the steps are still the same.

TVB

1.) Open a blank Word document and click anywhere in the document.

2.) On the main menu, click Insert > Quick Parts > Field.

3.) In the Field dialog box, in the Field names list, select Seq. (Note how the Field codes field is automatically populated with the field code of Seq.)

Field_dialog_box

4.) After the field of SEQ, enter the code for the field with the following information:

  • The name of the field.
  • The field type. (By default, unless otherwise specified, the field type is assumed to be a numbered field.)
  • The starting number for the field, which indicates whether the field is to be a beginning field (for example, a “1” or an “a”), or a continuation field (for example, “2” or greater, or “b” or greater).

Here is an example of setting up a field code for a numbered list that is to begin with a “1″ where “numberlist” is the name of the list and the switch \r 1 indicates that the list is to be reset to “1.”

SEQ numberlist \r 1

  • Note that there is a space between numberlist and the backslash and there is a space between the “r” and the “1.”
  • It’s also important to note that I have named the field as “numberlist,” and by default, unless otherwise specified, Word assumes that the field code is to be used for a numbered list. You will see how to indicate an alphabetic list later in this lesson.

5.) Clear the Preserve formatting during updates option.

Field_dialog_box2

6.) Click OK and the number “1” is displayed where you clicked in the blank Word document.

7.) Select the “1” that is displayed, right-click it, and on the context menu that opens, select Toggle Field Codes to display and automatically select the field code for the number.

Field_code_selected

8.) After the last right curly bracket in the selected field code, type a period, press the Tab key, and then enter a space after the tab.

Field_code_space_tab

9.) Select all of the above code with the exception of the space. (Yes, this does mean select the tab character as well. This easiest way to select all but the space is to place the cursor at the beginning of the field code, hold down the Shift key, and then press the Right arrow key as needed until all but the tab is selected.)Field_code_selected_nopsace

10.) Open the AutoCorrect dialog box. (In Word 2007, this means clicking the Office 2007 button (which, to me, looks like an obnoxious knock-off of the Olympic Rings in the upper left corner of Word), and then clicking Word Options > Proofing > Autocorrect Options.)

AutoCorrect_dialogbox

11.) In the Replace field, enter the shorthand notation that you want to use for a paragraph that is to be numbered “1” in any of your Word documents. For example, in my Word installation, I entered  1], which is the number 1 followed by a right bracket ( ] ).

12.) Make sure that the option of Formatted text is selected.

13.) Click Add, and then click OK.

Now, every time that you want a paragraph to begin with a “1,” you need to simply enter a “1” followed by a right bracket “( ] ) and press Enter. The paragraph is numbered with a “1” that is followed by a period and a tab. You can then use Word Styles to change indent levels, and so on for different levels of numbered lists.

To repeat this procedure for continuation numbers for numberlist, make sure that the code for the continuation numbers is named identically– SEQ numberlist \n – where the \n is the switch that indicates to continue numbering the numberlist paragraph. (In my Word installation, I use a “2” followed by a right bracket ( ] ) to for my replacement text.)

For lower case alphabetic lists, I named the list “alphalist,” and the codes for lower case letters are as follows (noting that, unlike numbered lists, you must specify not only the switch, but also, that the numbered list type is to be a lower case alphabetic list. This requires the insertion of \* alphabetic between the list name of “alphalist” and the list switch of either \r 1 or \n).

  • SEQ alphalist \* alphabetic \r 1
  • SEQ alphalist \* alphabetic \n

For the replacement text, in my Word installation, I use a lower case “a” followed by a right bracket ( ] ) for the beginning letter “a” and I use a lower case “b” followed by a right bracket ( ] ) to indicate continue with “b” or greater.

For upper case alphabetic lists, the code for the numbered list type is Alphabetic (note the upper case “A.”) Also note that in the Auto Correct dialog box, a distinction is NOT made between upper case and lower case letters in the Replace field. For example, if you indicated that a] was to be used for the beginning lowercase “a,” you could not enter A] as the replacement text that is to be used for the beginning upper case letters. Word would automatically change the upper case A to a lower case a and you would wind up with two identical replacement codes to mean two different things and this simply won’t work! In my Word installation, I used an upper case A followed by a right curly bracket ( A} ) and an upper case B followed by a right curly bracket ( B} ) as my replacement text for upper case alphabetic lists.

Updating after you insert or delete a numbered paragraph is now easy and straight forward. If you insert or delete a numbered paragraph in a Word document, simply select any numbered paragraph in the list, right-click on the selected paragraph, and on the context menu that opens, click Update Field. The picture below illustrates this:

AllSteps

  • I decided that I needed to insert a step between Step C and Step D.
  • After insertion using the replacement code of B}, Step D was indeed inserted after Step C and what was the previous Step D.
  • I select and right-click on what was the previous Step D, and on the context menu that opens, click Update Field.
  • The previous Step D now becomes Step E as needed.

 

{ 1 comment }

Resizing Visio Swim Lanes

by tammyvb on October 14, 2011

Ah, “swimlanes!” Gotta’ love the term. Ever tried to resize a swim lane in a cross-functional flowchart in Visio and dealt with the frustrations of the swim lane “swimming” all around instead of resizing? Well, there is a way not only to resize swim lanes, but also, to keep all your swim lanes in the same view, even when the Visio diagram extends beyond a single page. (And FWIW, if you try googling this topic, you will find that Microsoft doesn’t refer to swim lanes as swim lanes – the very unfamiliar term of “band” is used instead. And, no amount of googling resulted in a hit about resizing either with the term “swim lane” or the term “band.” Evidently, it’s a trade secret that Microsoft wants to keep secret!)

Please note: This is specific for Visio 2007 and might be different for other versions of Visio. Googling the terms used in this post and your version of Visio might help you resolve the differences.

1.) Open a blank Visio document.

2.) On the main menu, click File > New > Cross-Functional Flowchart with whatever units and direction you prefer. (In this example, we will use US Units and horizontal.)

3.) Add a single band.

4.) Select the entire band in two steps.

  • First, click on the Title section of the band (the section with the placeholder of <Function>).
  • Second, click on the bottom horizontal line of the band itself. The band should be highlighted as shown in the figure below.

image

5.) Right-click on the selected bottom band, and then under Format, select Protection and clear the option for Height.

6.) Right-click on the selected bottom band and under Format, select Behavior, and then under Resize Behavior, select Reposition Only.

7.) Select only the Title section and then hold your cursor over the middle button until the cursor changes to a double-headed arrow and the Resize Shape tooltip is displayed as shown in the figure below.

image

8.) Click and hold the cursor on the middle button and drag to resize the band.

9.) Add the necessary Visio objects to the resized band.

Note: You can resize a band after you have added objects to the band only if the objects are not connected to other objects across bands.

8.) Repeat this procedure for each band that is to be added to the flowchart.

9.) Optionally, if the number of bands will exceed the vertical length of the page display, then under File > Page Setup > Page Size, select Size to fit drawing option. This results in all the bands being displayed on a single page.

{ 22 comments }

SiteLock