�ݺ�ߣ

Text Insets A FrameMaker Single-Sourcing Solution Jack Shasha

FrameMaker��s Approach to Single-Sourcing Text insets is FrameMaker��s way to boilerplate chunks of text, graphics and tables By using a common template, a single inset source can ��fit�� into different target FrameMaker documents With variables and conditional text , an inset accommodates for variations between target documents

What are Text Insets? A combination of FM text, tables and graphics that are imported by reference Target documents are always linked to the source files and updated when the source file is revised Normally, a text inset would be a few pages, or even a single paragraph You can even use a whole chapter as a text inset, but this is best done in a book file

Text Insets Imported into Target Docs

Advantages A description or procedure is changed once only (the principle of single-sourcing) A well-designed text inset with variables and conditional text automatically adapts to the target document Import an inset rather than send the reader elsewhere for information

Folder Rules Plan your documentation folders well so there will not be a need to change in the future Changing the folder structure and/or the names of insets after insertion, will require their re-linking Target Doc: If you Save As to another location, FrameMaker automatically renews the links to the insets

Considerations re Folder Naming Give a common name to the document folders and the text inset sub-folders so you can easily recognize where they belong For example, the place for an inset for the Installation manual in the Installation sub-folder of the Text Insets. Give it a name that indicates where in the Installation manual it can be found. For example: Config-Device_Step3.fm TRW-Module_Intro.fm Routing-Table_Client-entries.fm

Common Template Use the FrameMaker template that you will be using for all your documentation and create a blank Inset.fm file. Use this for all insets. With a common template, you can have a number of target docs, each with the same paratags but with different formatting (font, colors, spaces)

Content Considerations A critical issue is: ��What constitutes an inset?�� Make it small enough so it can fit into target docs without extra information that may be redundant in one of the targets. You can always add another inset if you need it. Cut down on the text. This is good as a general rule, but especially so in insets. Add a diagram or graphic if it can explain it better (a workflow for a procedure, or a block diagram for a concept)

Inset Headings Try to create insets without major headings; use minor headings that fit nicely into your target docs Insert the inset under a major heading in the destination doc. Set Xrefs to content in the insets to refer to headings within the Target Doc

Conditional Text Conditional Text should be defined in the text inset, then specify Hide/Show in the target documents. Can be text, graphics or tables

Using Variables Most common use of variables is for names of modules, models, functions, or options. For example, we have the same inset describing a function in two devices Set a variable in the inset with the name of the device. Give the variable the same name in both target documents When importing the inset, the variable will take on the name specified in each target.

Nested Text Insets Inserting an inset into another inset can be useful when they can be used both as a single unit and separately. For example, a main inset is used as an appendix describing the main window of an application. The main inset is made up of sub-insets, each describing usage for individual modules. Each sub-inset can be inserted separately in the module descriptions. Remember that all the limitations of an inset apply also to nested insets, such as no Xref to the local doc.

Cross-references from/to Text Insets In FrameMaker, a Xref to an inset takes you to the beginning of the inset In the PDF it takes you to the exact location Hyperlinks in insets to external websites work Xrefs in insets to external docs do not work (when you insert a Xref in a source inset it is in a different location)

Using Text Insets in a Glossary Generate your technical glossary with text insets Use glossary descriptions in your manuals as an introduction to the subject Justified when the descriptions are long

What to look out for in Text Insets? Local Xrefs in the inset to locations in the target doc do not work Extra paragraph marks at the end or within the inset show up in the target doc. Manual formatting overrides: Although they will probably be unchanged in the target, it is best to avoid them When importing an inset into a table, an extra paragraph tag is added

Creating a Text Inset To create an inset, it is best to write it with FrameMaker in order to retain the formatting You can write a file with any text editor, but you need to paste the unformatted text into a blank Inset.fm and format it according to the template Save the inset in the appropriate folder under the relevant name

Importing Text Insets Click on the paragraph mark where to insert. Select File > Import > File. Accept the default: Body Page Flow = A (Main Flow). Accept: Reformat Using Current Document��s Format Accept: Updating of Imported Flow = Automatic. Click Import

Setting the Import Parameters Body Flow enables you to select which body flow from text inset to integrate into the main flow of the target. Reformat to target doc so the inset will take on the existing formatting and variables Use: ��Remove Manual Page Breaks�� and ��Remove Other Format Overrides�� if you have them in the inset. Manual page breaks affect your pagination in the target.

Accessing a Text Inset from the Target From the target doc

Changing Inset Names / Locations References get broken when changing: Names of text insets Locations When you open the FM target doc, you will be notified: ��Unresolved Text Insets�� Perform a Find, click ��Open Source��, find the name and search for the missing inset If you do not need the inset anymore, do a Convert to Text

Changes in the Template What happens if you change your template after inserting your text insets? Create a Book File of your text insets: One large Book File of all your insets Or, a Book File in each inset sub-folder Import Formats from the changed template

Idiosyncrasies You can re-format the inset with a different paratag in the target doc. The whole inset must be re-formatted; you cannot format individual paragraphs The text import option ��Reformat using current document��s formats�� must be activated

Multiple Writers Consistent writing styles Use variables where feasible to avoid capitalization and other inconsistencies between writers Create a map (either as text or as a diagram) linking insets to their target docs Give target docs a look-over to see if insets have been inserted in the wrong locations

Drawbacks From my experience, the maximum number of text insets imported into a FM doc. is about 350. Over that number, the FM file does not load (using FrameMaker V7.2). Solution: Split up the main file into a number of smaller files, the number depending on expected growth in the file.

Thank you for watching Jack Shasha [email_address]

�ݺ�ߣ

Fm Text Insets

Recommended

More Related Content

Similar to Fm Text Insets (20)

Recently uploaded (20)

Fm Text Insets