The Mif2Go User's Guide is a perpetual work-in-progress, largely unreviewed. See history.txt in the Mif2Go distribution for updates to the software that are not mentioned in this guide or in the on-line Help.
This section identifies substantive additions and corrections since prior editions. Corrections are shown in red.
• No “quick start” this time! Omni Systems has massively reorganized the Mif2Go distribution; see §1.3.1 Set up a framework for Omni Systems applications.
• System-wide configuration file. Specify in one place any settings that apply to all projects; see §1.3.6 Establish system-wide configuration settings.
• All Mif2Go executables are now referenced from the new Omni Systems directory structure, not from the Windows system directory. See §1.4.2 Update your Mif2Go installation.
Planning a conversion project:
• Produce a single output file from a FrameMaker book. You really need a script to do this right; see §2.5.6 Producing a single output file from a FrameMaker book.
• New names for project configuration files! Each is now named for its output type; see §5.1.1 Checking output type and file extension.
• Keep at least one line of header text. Each configuration file must start with a header line; see §4.3 Understanding the rules for configuration settings.
• No more than one space after a key=value equals sign. Do not try to line up values vertically with extra spaces after the equals (before is usually OK, though not always); see §4.3 Understanding the rules for configuration settings.
• Comment out entire configuration sections with a single semicolon. New tip; see §4.6 Commenting out configuration sections.
Setting basic conversion options:
• Append log files to a history file. New setting HistoryFileName; see §5.2 Logging conversion events.
• ObjectIDs change on show/hide conditional text. Always! So use carefully; see §5.3.2 Working with FrameMaker ObjectIDs.
• Condition show/hide settings might not work in FrameMaker 10+. Go back to importing FrameMaker templates instead; see §5.4.1 Applying condition Show/Hide settings.
• Include a suffix in generated equation file names. New setting EqSuffix; see §5.8.4 Providing a file-name suffix for equations.
• Specify a Windows code page for print RTF output. New setting CodePage; see §6.2.4 Specifying the default output language and code page.
• Keep trailing tabs in Word output. New setting TrailingTabs; see §6.8.3 Altering tab behavior for Word output.
• Produce .doc or .docx files via Word macro and a SystemEndCommand. See §6.16.1 Supporting more than one version of Word.
• Produce index meta elements for Microsoft Help Viewer. New setting UseHVIndex, new custom marker type HVIndex; see §7.5.2 Preparing index entries for Microsoft Help Viewer.
• Provide a sort order for Japanese index entries. Most likely you will need help; see §7.5.9.5 Defining Japanese index sort order.
• Get WinHelp viewers from Microsoft. And so must every user; see §8.1 Obtaining tools for WinHelp
• Tell Mif2Go where to find the WinHelp compiler. Previously undocumented setting Compiler; see §8.2.12 Compiling a WinHelp project.
• Specify copyright and date for WinHelp Version Information. Previously undocumented settings HelpCopyright and HelpCopyDate; see §8.2.12 Compiling a WinHelp project.
• Insert a separator between text and footnotes in WinHelp. New setting FootnoteSeparator; see §8.3.6 Converting footnotes.
• Specify table width when you use column-width percentages for WinHelp. New setting TblFullWidth; see §8.5.2 Adjusting table appearance.
Generating Microsoft HTML Help:
• Omit code-page mapping for uncompiled HTML Help. New setting UseCodePage; see §9.2.6 Deciding whether to compile HTML Help.
• Generate Asian or Cyrillic HTML Help. New code-page DLLs; see §9.12 Generating HTML Help in non-Western languages.
• Fixed spaces become ideographs for Japanese HTML Help. Or you can map them to something else; see §9.12 Generating HTML Help in non-Western languages.
• Tell Mif2Go where to find the HTML Help compiler. New setting Compiler; see §9.13.1 Directing Mif2Go to run the HTML Help compiler.
• Compile HTML Help in a different locale. Use command-line utility SBAppLocale; see §9.13.3 Compiling in a different language.
• Include relative paths in OmniHelp subprojects to be merged. See §10.12.2 Listing and mapping OmniHelp subprojects.
Generating JavaHelp or Oracle Help:
• Specify options for Oracle Help in their own eponymous section. New section [OracleHelpOptions]; for example, see §11.3.7.2 Letting Mif2Go set up the directory structure and copy files.
• Add type attribute to list tags for JavaHelp and Oracle Help. New CSS setting UseListTypeAttribute; see:
§11.3.9 Coping with JavaHelp / Oracle Help viewer limitations
§21.11.2.7 Including or excluding the type list attribute.
• For ePub, XHTML output can provide input to Calibre. See §13.1 Deciding which type of output to produce.
• For HTML 5 output, set DOCTYPE as appropriate. See §13.4.1 Specifying HTML/XML version, DOCTYPE, and DTD.
• Omit generator information from HTML output (not advisable). Previously undocumented setting [HtmlOptions]GeneratorTag=None; see §13.4.4 Including or omitting HTML/XML generator information.
• Include a main or “index” page for HTML output. New setting GenerateIndexHTML; see §13.6.3 Providing a main or “index” page for HTML.
• Show FrameMaker condition indicators in HTML output. New section [ConditionOptions]; new settings UseConditionalFlagging, CSSFlagsFile, WriteFlagsFile, and ReferenceFlagsFile. See §13.11.3 Displaying condition indicators in HTML with CSS.
• Supply hover text for terms and acronyms in HTML. New format property GlossTitle, new sections [GlossTitles]and [GlossFiles]; see §13.12 Creating hover text for terms in HTML.
• Turn on UseSpacers explicitly to indent tables and figures! Important if your output relies on this setting, because the default value has been changed to No. See:
• Keep Shift+Enter line breaks. New setting UseXMLbr; see §14.4.5 Configuring forced returns for XML.
• Map formats to elements depending on topic type. New functionality in [DITAAliases], new predefined macro variable $$_ditastart; see §15.4.3.8 Mapping paragraph format aliases algorithmically.
• Replace change bars or overlines with tags for DITA XML output. When UseTypographicElements=Yes, you get <chbar> and <over> elements, respectively; see §15.4.4.2 Including typographic elements in addition to mapped formats.
• Give every DITA element that can accommodate it an ID. New setting SetElementIDs; see §15.4.6.2 Including an id attribute in every element.
• Specify attributes for the root element of a topic. New section [DITATopicRootAttrs], new marker type DITATopicRootAttrs; see §15.4.6.3 Specifying attribute values for the root element of a topic.
• Include an outputclass attribute in the DITA XML root element. New marker type DITATopicOutputclass; see §15.4.6.6 Providing outputclass attributes for all elements.
• Configure nested lists for DITA XML. See §15.5.7 Configuring nested lists.
• Use relative or absolute table widths in DITA XML. New setting TableColsRelative; see §15.6.4.3 Specifying relative vs. absolute widths for table columns.
• Specify placement of figure titles for DITA. New setting FigureTitleStartsFigure; see §15.7.2 Specifying what to include in a <fig> wrapper.
• Omit size attributes from images for DITA. Newly applicable setting [Graphics]GraphScale; see §15.7.3 Omitting size attributes from images.
• Include MathFullForm equation objects in <alt> text. New setting MathFullForm; see §15.7.5 Including MathFullForm equations in <alt> elements.
• Include FrameMaker DPI values in <image> attributes. New setting UseOtherpropsDPI; see §15.7.6 Including the original image DPI as an attribute.
• Rename DITA topic files to make the file names readable. FrameScript method; see §15.8.3.2 Renaming DITA topic files with FrameScript.
• Specify an outputclass attribute for cross-reference wrappers. New settings XrefWrapClass, FootnoteWrapClass, and IndexWrapClass; see §15.10.2 Specifying an outputclass for cross-reference wrappers.
• Adjust map levels for missing heading levels. See §16.2.3 Accounting for missing topic levels.
• Include DITA bookmap <appendix> elements in <part>. New setting AllowPartAppendix; see §16.3.4 Extending <part> to include <appendix>.
• Exclude book-level reltable from a bookmap. New setting MapBookRelTable; see §16.3.6 Excluding the book-level reltable from a bookmap.
• Include multiple TOCs, indexes, other booklist items in a bookmap. New sections [IndexMarkerOutputClass], [DITABookmapOutputclasses]; see §16.4.3 Including multiple booklist components of the same type.
• Accommodate placeholders for extra bookmap elements. New sections [BookmapElementBefore], [BookmapElementAfter]; see §16.4.7 Including placeholders for additional bookmap elements.
• Allow multiple images in a figure element for DocBook. Newly applicable setting MultiImageFigures; see §17.7.1 Deciding what to include in a figure element.
• Include additional content in figure elements for DocBook. Newly applicable setting CloseFigAfterImage; see §17.7.1 Deciding what to include in a figure element.
• Specify placement of figure titles for DocBook. New setting FigureTitleStartsFigure; see §17.7.1 Deciding what to include in a figure element.
• Omit size attributes from images for DocBook. Newly applicable setting [Graphics]GraphScale; see §17.7.3 Omitting size attributes from images.
Splitting and extracting files:
• Insert space or a separator between HTML topics in a single output file. New [Inserts] keyword TopicBreak; see:
§18.5.2 Assigning code to [Inserts] keywords for splits and extracts
§28.9.2 Invoking macros at predetermined points in output.
• Replace spaces in links with hyphens or underscores. Instead of only alphanumerics for XrefSpaceChar or HyperSpaceChar; see §19.2.5 Replacing problem characters in links.
Mapping text formats to HTML/XML:
• Prevent line breaks and preserve leading spaces at the paragraph format level. New [HtmlStyles] format property NoWrap; see §21.3.7 Stripping paragraph properties.
• Font tags are now excluded from HTML output by default. The default values for NoFonts and NoSymbolFont have been reversed; see:
§21.6.4 Including or excluding font tags
§21.6.5 Managing font tags for symbol fonts
• Replace change bars or overlines with tags for HTML/XML output. Use new “pseudo tag” names chbar and over; see §21.7.2 Choosing how to treat typographic elements.
• Replace spaces in CSS class names with hyphens or underscores. Instead of only alphanumerics as a value for ClassSpaceChar; see §22.7.1 Understanding CSS class name restrictions.
• Flag alternate-language glyphs with CSS classes. New setting UseCharRangeClasses, new section [CharacterRangeClasses]; see §22.7.6 Assigning CSS classes based on Unicode character ranges.
• HTML image indent spacer default has been reversed. If you rely on this deprecated technique, you must explicitly set UseSpacers=Yes; see §23.6.3 Indenting images.
• Omit empty alt attribute values from HTML output. New setting AllowEmptyAlt; see §23.8 Providing (or omitting) alternate text for images.
• HTML table indent spacer default is reversed. If you rely on this deprecated technique, you must explicitly set UseSpacers=Yes; see §24.5.1 Indenting tables.
• Strip HTML code from selected tables. With configuration macros or Config markers; see:
§24.6.4 Turning processing on and off around selected tables
§24.7.2 Removing table-specific tags from selected tables.
• Add a visible trailing space to a macro. New convention “\~” for trailing spaces; see §28.1.1.3 Escaping special characters in macro definitions.
• Predefined macro variables for project name and path.
New variable $$_prjname; also, variable $$_prjpath can now be used in macros as well as in
system commands. See Table 28
• More ways to manipulate strings. New macro
expression operators lower, upper, and replace
with; see Table 28
• Pass a parameter to a macro, and capture its value. New predefined macro variable $$_macroparam; see §28.7 Passing a parameter to a macro.
Working with FrameMaker markers:
• Treat marker content as plain text for XML output. New marker property type Text; see §29.7.3 Processing marker content as text for XML/HTML/XHTML.
• Configuration templates play a major role now. New [Templates] section with new settings Document, Configs, and Macros; see §30.1 Working with configuration templates.
• [FDK]ConfigTemplate is deprecated in favor of [Templates]Configs. Replace all instances of the former; see §30.2 Referencing configuration files and templates.
• Include one or more templates for document-specific settings. New setting [Templates]Document; see §30.3 Including document-specific configuration files.
• Extract embedded graphics imported from Word. Without knowing their formats; see §31.2.7 Exporting embedded graphics imported from Word.
Automating Mif2Go conversions:
• System-command keywords have new names, new configuration section:
See §34.4.1 Specifying system commands.
• Whip FrameMaker variables into shape for use in file names. Whack spaces and punctuation with macros; see §34.8.4.2 Including FrameMaker variables in output file names.
• Use variable <$$_objectid> in file names. To guarantee uniqueness, if you are determined to name output files yourself; see §34.8.4.5 Specifying a file-name prefix or suffix.
Producing deliverable results:
• Copy ancillary files before and after conversion. New [Automation] settings CopyBeforeFrom, CopyBeforeFiles, CopyAfterFrom, CopyAfterFiles; see:
§35.5 Gathering additional files before converting
§35.6.6 Listing extracurricular files to put in the wrap directory.
• Default value of WrapPath is now .\_wrap, relative to the project directory; see §35.6.1 Specifying a wrap directory.
• Gather referenced graphics files for distribution. New setting CopyOriginalGraphics; see §35.7.1 Copying referenced graphics to a distribution directory.
• Default value of ShipPath is now ..\..\_ship, relative to the project directory; see §35.12.1 Specifying a shipping directory for deliverables.
• Log in as administrator before you set up runfm. Because you must write to the Windows Registry; see §36.2 Setting up FrameMaker for unattended operation.