Describes the DITA map and topic authoring commands as well as the enhanced DITA publishing features.
DITA-FMx is a plugin and set of structure applications that let you create and edit DITA XML files in FrameMaker. DITA-FMx 2.0 supports DITA 1.2 (and earlier versions) as well as Lightweight DITA (as of v.2.0.06) and is available for FrameMaker versions 7.2 through 2020.
For a complete list of changes between versions of DITA-FMx, see Revision History. The following describes the general features provided by DITA-FMx.
A Map structure application is provided that allows for creation and editing of both DITA 1.2 map and bookmap files. When saved to disk, the resulting DITA map file is completely DITA-compliant, although within the FrameMaker authoring environment some additional elements are added to provide a more efficient authoring experience. This Map application also provides complete support for relationship tables as well as key definitions (keydef).
The Build Map from Outline command creates a DITA map and optionally DITA topic stub files from a simple FrameMaker file.
The Build WorkBook from Map command creates a FrameMaker book file that contains all of the files referenced in the current DITA map and all submaps. This “work book” is not intended to be used for publishing, but facilitates the use of FrameMaker’s built-in book processing commands such as spell checking and searching at the book level. In order to use these book processing commands on the work book you must first open all of the files in the book. This can be done with the Open All XML Files in Book command which provides the option to resolve references in each file, or open the files without resolving references.
As of DITA-FMx 2.0.06, a set of LwDITA-FMx structure applications are provided, which are based on the current (as of July 2017) DTDs being developed by the DITA TC at OASIS. With these applications you can author and publish using Lightweight DITA.
If enabled in the Auto-Prolog Options dialog, author and date metadata is automatically updated and added to the prolog in topics and bookmeta/topicmeta in maps.
When a draft-comment element is inserted, the author and time attributes are automatically set to the values defined in the Authoring Options dialog.
Filtering based on ditaval files can be applied to content in FrameMaker books and files using the Apply Ditaval command. This filtering can be done via conditionalization or by element deletion. Ditaval files can also be specified for output generated through the Open Toolkit (using the Generate Output command). The Ditaval Manager provides an easy to use interface for creating and managing ditaval files. A ditaval file can also be specified when generating a FrameMaker book using the Generate Book from Map command.
Keys provide an alternate method of referencing. A key name is bound to a reference using a key definition (keydef) in a map. This key name can be used in place of (or in addition to) an href reference (a direct reference to a file). A keyspace is comprised of all key definitions in a map (and submaps), optionally filtered by an associated ditaval file.
DITA-FMx provides support for key references to files as well as key references to elements (key element references).
Using a term element to create a key element reference to a glossary entry will render the text of the glossary entry’s title (glossterm element). If you enable the Glossary Term Swapping option (in the Book Build Settings dialog), the term will render the glossSurfaceForm content in the first instance of the term in a chapter, and the value of glossAlt (glossAcronym or glossAbbreviation) for remaining instances.
Content references allow reuse of elements from the same file or other files on the same file system. DITA-FMx supports the use of conref ranges as well as conref specification by key reference (conkeyref).
If enabled (through the Options command) on the opening of a file, the content included by conref is resolved and displayed as a locked text range (similar to a text inset). The Flatten Conref command is available to “unlock” conrefs when saved as FM binary files.
On the opening of a file, all xref and link elements are resolved and displayed as a locked text range. The auto-loading functionality may be enabled/disabled with the Options command.
When an xref or link element is inserted (from the element catalog), the Reference Manager dialog displays allowing you to select the target element for that element (through a direct reference or a key reference). Unless you enter text in the Alternate Xref Text field, the xref or link text will match that of the target element. The External Xref button lets you create an xref or link to an external file.
The Xref to Hyperlink command converts DITA-based xrefs and links into live hyperlinks in generated FM files.
DITA-FMx handles both DITA-based and FM-based cross-refs as both xref and link elements, for more information see Setting Up to Use Cross-References.
The coderef element allows you to include the content of a non-DITA “code” file within a codeblock element. The Coderef Manager lets you create that reference as well as edit the content of the referenced file.
The Set Attributes command provides quick and easy access to setting attributes on elements. This command makes use of the FrameMaker “Strings” attribute type and allows you to select one or more default values that are applied to the attribute. This is particularly useful with the DITA filtering attributes. This command also makes use of attributes defined as the “String” type and allows you to predefine a list of available values that are displayed as a scrolling list.
DITA-FMx supports the FMx-Auto “addon” from Leximation to unlock the extended API features in DITA-FMx. This API can be used for automated publishing as well as other types of scripted or automated processing.
The Generate Book from Map command builds a FrameMaker book from a DITA map or bookmap. It creates aggregated FM files from the top-level topic references and their child topicrefs (appropriate FM files are created from “part” files as well as frontmatter and backmatter files). Also offers the ability to include FM binary files in the generated book so you can mix DITA and unstructured FM files as needed. This allows you to generate a PDF book of an entire map. You can also pass this book to RoboHelp or Webworks ePublisher as one option for creating online Help.
Numerous options are available to automate portions of the book build, including the following:
DITA-FMx integrates with all versions of the DITA Open Toolkit. Versions prior to 2.0 require additional setup, but recent versions are virtually “plug and play.” Version 3.2 or later allows use of the DynamicTargets option which automatically lists all available publishing targets.
The Generate Output command provides the ability to run a specific target in an Ant script to generate output through the DITA Open Toolkit. One option lets you use a provided Ant script to generate output based on the current file (a topic or map), or another option lets you select a target in an Ant script that you provide. Using the Current File option, you can specify a ditaval file for filtering. For more information see, Generate Output.
DITA-FMx includes integration with DITA2Go (from Omni Systems at dita2go.omsys.com) as an alternative to the DITA-OT for creation of various types of online Help. If DITA2Go is installed, the “DITA2Go Project Manager” menu item will be available on the DITA-FMx menu.
The Search in Files command lets you search for content in files within a folder (and sub-folders) or in files referenced by a DITA map. The search criteria can be a mix of textual content, element or attribute names, or attribute value.
The Where Used command generates a report listing all files that reference the selected element or current topic.
The Reference Report command generates a report of all referenced files in a DITA map or topic file (as well as all references in all referenced files). This report can list unresolved and/or resolved references, as well as specific reference types (topicref, xref/link, conref, and image).
The Create Archive command generates a ZIP archive of the current file and all referenced files.
If enabled in the Authoring Options dialog, FrameMaker variables are wrapped in fm-var elements, which round-trip to DITA as ph elements. The variable name is preserved as a special value in the outputclass attribute which allows it to round-trip successfully.
The “book-build” process provides the ability to import metadata (attributes and content values) from the map into the generated FM files as variables. This lets you update variables in the headers and footers as well as variables in binary FM files (like those used for the title page and other frontmatter).
Textual callouts and graphic objects within an anchored frame will now round-trip from FrameMaker to DITA and back. The data to define these objects is stored in the DITA data element.
An Options command provides the ability to specify the structure applications for DITA map and topic file authoring, the structure application used for the book processing, as well as control of various DITA-FMx options.
You can get context-sensitive help for DITA authoring by pressing Alt+F1. The DITA Reference displays the topic that relates to the element currently selected. If you have added elements through specialization, you can add information about your elements to the CHM file (the source is provided in the DITA Open Toolkit).
DITA-FMx should fully support specialization (or at least not hinder it). If you have a specialized data model, you will need to make the parallel changes to your DITA EDD and r/w rules. The only effect of specialized elements is with regard to element names, and the only place DITA-FMx operates solely on element names is with the processing of tables (and in this case, additional table elements can be defined in the ditafmx.ini file). In all other cases, DITA-FMx processes elements based on their class name, so it should properly handle specialized elements.
DITA-FMx fully supports all DITA table types including simpletable-based tables. Users who create specialized tables can ensure that they are properly rendered by including them in the Element Mapping dialog via the Options dialog.
DITA-FMx provides support for complex table formatting through the use of predefined table formats as well as preserving table widths and the state of rotated table cells, in addition to indenting tables based on the left indent of the parent element. Custom ruling and shading can be applied to rows and cells by preconfiguring a reference page table and assigning outputclass attribute values.
DITA-FMx provides special support for authoring and publishing of hazardstatement elements. When using the default Topic structure application, thehazardsymbol element will move into a sensible location while authoring. When publishing with the default Book structure application, the hazardstatement elements will be wrapped in a table structure with a special header and coloring based on the hazard type (attribute). For additional information on this feature, see DITA-FMx Specific Book Application Elements.
On file open, DITA-FMx converts indexterm elements to a FrameMaker-compatible syntax within Index markers. DITA specifies that index subentries are defined by nested indexterm elements. This feature collapses nested indexterm elements into a single semicolon-delimited string within the top-level indexterm element which can be properly interpreted by FrameMaker and converted into an Index marker. This functionality keys off of the value of the class attribute, allowing it to work for specialized instances of the indexterm element. On file save, the Index markers are converted back to valid nested indexterm elements. If necessary, in order to support more complex element structures within indexterm elements, you can disable the conversion to markers.
All textual references (topic references, conrefs, xrefs, and links) are represented in FrameMaker as locked text ranges similar to text insets. These text ranges are not linked to text flows but are used as a means to lock a region of text and allow the user to click on the object. In order to maintain valid DITA files, DITA-FMx converts these text ranges to the appropriate XML structure on file save.
DITA-FMx provides a mechanism to apply language-specific templates based on the topic/@xml:lang attribute value. This attribute value can also be used to specify language-specific book-build options. For more information see the “UseLanguageTemplate” parameter in INI-Only Settings.
DITA-FMx seamlessly integrates with the Bluestream XDocs CMS through the XDocsFMx plugin (available at no cost). Customers have also had success with integrations of DITA-FMx and SDL Trisoft as well as Vasont. We also have development prototypes to integrate DITA-FMx with the easyDITA CMS.
Using FMx-Auto, DITA-FMx can be set up on the back end of most CMSes and used as a PDF publishing engine. To learn more about this support and options visit www.leximation.com/dita-fmx/cms-support.