New information

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.

2012 May 1, update 4u54

Getting started with Mif2Go:

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.

Editing configuration files:

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.

Converting to print RTF:

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.

Producing on-line Help:

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.

Generating WinHelp:

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.

Generating OmniHelp:

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.

Converting to HTML/XHTML:

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:

§23.6.3 Indenting images

§24.5.1 Indenting tables.

Converting to generic XML:

Keep Shift+Enter line breaks. New setting UseXMLbr; see §14.4.5 Configuring forced returns for XML.

Converting to DITA 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.

Configuring DITA maps:

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.

Converting to DocBook XML:

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.

Creating HTML links:

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.

Setting up CSS for HTML:

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.

Including graphics in HTML:

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.

Converting tables to HTML:

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.

Working with macros:

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

More ways to manipulate strings. New macro expression operators lower, upper, and replace with; see Table 28-4 Operators for HTML macro expressions.

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.

Working with templates:

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.

Working with graphics:

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

[spacer]

Old

New

[BookFileCommands]

[Automation]

BookStartCommand

SystemStartCommand

BookWrapCommand

SystemWrapCommand

BookEndCommand

SystemEndCommand

FileStartCommand

SystemStartCommand

FileWrapCommand

SystemWrapCommand

FileEndCommand

SystemEndCommand

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.

Converting via runfm:

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.