Fm Text Insets

  • 2,425 views
Uploaded on

Presentation on the use of text insets in FrameMaker 7.2

Presentation on the use of text insets in FrameMaker 7.2

More in: Technology
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
    Be the first to like this
No Downloads

Views

Total Views
2,425
On Slideshare
0
From Embeds
0
Number of Embeds
1

Actions

Shares
Downloads
0
Comments
0
Likes
0

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

Transcript

  • 1. Text Insets A FrameMaker Single-Sourcing Solution Jack Shasha
  • 2. 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
  • 3. 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
  • 4. Text Insets Imported into Target Docs
  • 5. 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
  • 6. 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
  • 7. Structuring your Folders
  • 8. 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
  • 9. 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)
  • 10. 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)
  • 11. 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
  • 12. 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
  • 13. 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.
  • 14. 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.
  • 15. 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)
  • 16. 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
  • 17. 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
  • 18. 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
  • 19. 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
  • 20. 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.
  • 21. Accessing a Text Inset from the Target
    • From the target doc
  • 22. 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
  • 23. 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
  • 24. 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
  • 25. 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
  • 26. 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.
  • 27. Thank you for watching Jack Shasha [email_address]