Category Archives: FrameMaker

FrameMaker: EDD, template, rules – what is all that and how does it benefit me?

People often complain that it’s too hard to edit XML files in FrameMaker. Before you can effectively edit files you need to set up a structure application for that XML model. A structure application is a set of special files and instructions that tell FrameMaker how to apply formatting to the XML tags and content in an XML file. This information is stored in a file called the structure application definition file, which contains all of the “definitions” for each structure application available to FrameMaker.

If you’re given an XML file to edit, and are provided with the structure application for that XML model, it’s easy to install the structure application files and start editing. However, if you don’t have a structure application, creating one can require a bit of effort when all you want to do is make some edits. If it’s not important to work in a WYSIWYG mode, you can edit your XML file without setting up a structure application as long as the file includes a valid reference to a DTD. You can toggle the tags on or off and make edits to the content as needed. But if you’ll be doing any significant editing, it’s likely that you’ll want some amount of formatting (even if it’s just to distinguish between block and inline elements and make headings bold). This really isn’t all that different from other XML editors that provide a WYSIWYG or “Author” editing mode. They all require some type of configuration or setup to associate elements and contexts with a particular formatted representation of those elements.

Keep in mind that although FrameMaker is often associated with book production and page layout (which it excels in), the formatting applied by your structure application does not need to use or imply page-oriented formatting. In fact, you can make the formatting look very basic, like a simple web page. Personally, I like to encourage this approach when authoring XML documents. If you’re authoring XML, you are probably producing deliverables for many different output formats, and it’s best if the author is not writing with any of those output formats in mind. When working in this way, you’ll have two structure applications, one for authoring which uses a very simple layout, and one for publishing which applies the page-based formatting that you want in a printed book.

While FrameMaker is actually very similar to other XML editors in features and functionality, it’s important to keep in mind that FrameMaker is not just another XML editor. In addition to being an editor (for both unstructured and structured documents), it is also a state of the art print publishing engine. Most (all?) other XML editors require a completely different tool in order to render the XML tags and content into a format that is acceptable for a printed page or book. With FrameMaker you get both tools in one, and with that added power comes a bit more effort up front. This is a significant advantage, and in the long run, well worth the extra effort.

I like to think of the FrameMaker XML authoring process as “front-loading” the publishing effort. Once you can edit an XML file in FrameMaker, you can also get a beautiful PDF file ready for printing or online delivery. Other XML editors may allow you to edit the XML file quickly, but in order to generate a PDF, you’ll need to learn XSL-FO (or hire someone who knows it), then buy an FO rendering engine to create the PDF. (XSL-FO is an open source language for transforming XML into PDF.) Yes, there are other options for creating a PDF from XML other than XSL-FO, but they all require considerable amount of knowledge and coding and/or a considerable amount of money.

The icing on the cake is that a PDF generated from FrameMaker is likely to look much nicer than one generated from an FO-based process. XSL-FO just does not support the same level of formatting and layout as that available within FrameMaker, no matter how much time you spend on crafting the FO stylesheets.

Granted, there can be a fair amount of effort required to create a structure application from scratch. It’s often best to start by cloning an existing structure application, but if that’s not possible, you’ll just have to make one yourself or hire a consultant to develop one for you.

The core components of a structure application are:

DTD (Document Type Definition). A set of markup declarations that define the elements and their relationship in an XML or SGML data model. The DTD also defines any attributes and their default values.
EDD (Element Definition Document). Similar in concept to a DTD, but adds a layer of context rules to allow the mapping of formatting properties to the data model based on the relationship of elements and attribute values. An EDD can be created from a DTD, but the context rules must be added to assign formatting to the document when it is opened. The context rules can assign formatting properties directly, or it can assign paragraph and character styles that are defined in the template.
Template. A FrameMaker file that defines the page layout properties, named paragraph and character styles, and other document-specific settings. The EDD is imported into the template file, making the template a single file that contains both the structure rules and formatting information.
Read/write rules. A file that defines additional properties of specific elements and how those elements are modified as the XML file is read from or written to disk.
XSLT import or export stylesheet. You can optionally include XSLT stylesheets that perform additional processing on the import or export of an XML file.

References to all of these files (and other settings) are included in a structure application definition in the structure application definition file. For details and to learn all that you’ll need, refer to the Structure Application Developer’s Guide (http://www.adobe.com/support/documentation/en/framemaker/).

The nice thing is that once you have the structure application, even if you didn’t create it yourself, you’re likely to be able to make adjustments to the template to affect the layout or formatting of specific elements without assistance from a consultant. This is because you’re just changing properties of a standard FrameMaker template, something that you or someone in your company has probably been doing for years with unstructured FM files. If you’re using an FO-based process, unless you have the necessary expertise in-house, you may need to hire someone to make these modifications. You’ll hear people say that once the template is “set”, you don’t need to worry about further customizations, but that doesn’t mesh with the reality of the publishing process I’ve seen. People are always making little changes.

Another nice thing about using FrameMaker as your PDF publishing tool is the ability to leverage the “generated list” feature for creation of the Table of Contents, Index, and other front or back matter lists. As with the structure application template, setting up a nice looking Table of Contents or Index is just a matter of setting up a generated list template as done with unstructured FrameMaker. No special programming knowledge required, and it’s easy to test and modify as needed.

Publishing from FrameMaker can be done “by hand” on the desktop, by creating a book file from the XML content, then applying the necessary pagination and numbering properties and adding the generated list files. Or you can set up a publishing process that’s partially or completely automated. Because FrameMaker has extensive API support (FDK, ExtendScript, and FrameScript), there are many automation options. This does require purchasing automation add-on components or coding-up your own tools, but much of this can be achieved with minimal expense and/or training.

Both Adobe Technical Communication Suite (TCS) and FrameMaker Server provide a tight integration between FrameMaker and RoboHelp, so in addition to the PDF publishing offered by FrameMaker, you can publish to various types of online Help. This can provide an alternative to using XSL as the method for converting XML into HTML-based output.

When setting up an XML publishing workflow, people are often drawn to XSL and XSL-FO as the means to transform their XML content into online and print deliverables. In some cases one or both of these are in fact the right choice. But if it’s possible that the output formatting will require frequent modifications or if the level of formatting is not sufficient for your needs, FrameMaker is likely to be the best solution.

Because FrameMaker is a standards-compliant XML editor, it can be used in an authoring environment along side other XML editors. FrameMaker can also publish XML content that was authored in other XML editors. The great thing about XML is that it frees your content from being tied to a proprietary authoring or publishing tool. That doesn’t mean you won’t still need to use proprietary tools, you just have the flexibility to mix and match those tools as needed. Your task is to choose the right tools to match your needs. Keep in mind that FrameMaker is not just another XML editor, it might just be the best XML editor for your needs!

— Scott Prentice, President of Leximation, Inc.
Developer of DITA-FMx and FMx-Auto, tools that provide extended DITA authoring and publishing features in FrameMaker.

This article was also posted to the Adobe Technical Communication Blog.

Myth #2: FrameMaker is only appropriate for printed books

While it is true that FrameMaker excels at the creation of printed content and PDF files, there is absolutely no reason that it should be limited to the creation of chapter-based and book-centric content. FrameMaker works with files, you get to decide what those files represent .. books, chapters, sections, topics, or snippets. For years, people have been using FrameMaker along with tools like Mif2Go, WebWorks, and others, to create both PDF/print output as well as numerous online formats. In those workflows, people generally authored in unstructured, chapter-based files.

With the growing popularity of XML (and DITA in particular), FrameMaker can still be used to author content in a chapter-oriented paradigm, but it can also be used to author individual topics just as easily as any other XML editor. Using DITA maps to organize the topic files (which may represent books, chapters, or other collections). These map and topic can then be passed to external processing tools (like the DITA Open Toolkit) to be generated into specific deliverable formats, and can also be processed within FrameMaker to be assembled into books.

You might suggest that authoring in FrameMaker forces people to think in a book-centric manner because of the print format of the WYSIWYG authoring view. Although this may be the way you’ve seen FrameMaker used, this is completely up to you as the author to format the authoring view however it makes sense for your workflow and writers. When opening an XML file, you select a structure application to use, which applies a template which defined the way the content is rendered on screen. You can set up this structure application with a print-focused layout or you can choose to use fonts and a layout that looks very simple.

One example of this is found in the default DITA-FMx 1.1 Topic application which has no indents, uses Verdana as the font throughout and looks more like a web page than a printed book. If you choose to create a PDF from the DITA map and use the default Book application, the print formatting is applied. But while authoring, using the Topic application, you are encouraged to focus on the content rather than the formatting since it’s likely that you are creating deliverables for multiple output formats, of which print (PDF) is only one.

Just because FrameMaker has traditionally been the standard tool for authoring long documents doesn’t mean that it can’t be used for topic-based authoring as well. It is a very flexible and customizable authoring tool, which should be evaluated carefully with other tools when selecting an appropriate XML editor.

PDF Publishing with DITA-FMx 1.1

FrameMaker and DITA-FMx provide the easiest and least expensive way to get the highest quality PDF output from your DITA content. In addition to the numerous authoring features in DITA-FMx, it also provides many useful publishing options. Some of the more popular are listed below:

Add related links from relationship tables
Flatten conrefs and ensure that links are functional in PDF output
Apply ditaval filtering to the generated book files
Move figure titles so the follow the image
Enable table titles to display on all pages for tables that span pages
Assign proper numbering and pagination throughout the book
Replace “list” files with generated FrameMaker lists (e.g. TOC, Index)
Run custom scripts to perform additional pagination and cleanup

See how easy it is to get properly formatted PDF output from a DITA map using DITA-FMx. This video walks you through the basic process of configuring DITA-FMx for PDF publishing.

If you’re a new user of DITA-FMx or are considering a purchase, you should review this video.

» Link to video on YouTube.

Myth #1: FrameMaker isn’t a “real” XML editor

Well .. I guess you’d have to define “real XML editor,” but if by real you mean that the editor can open XML files on disk, and write the edited XML back to disk, then it’s as real as any other XML editor that I’ve seen. All XML editors have different features, and you may prefer one editor over another because of its features. But FrameMaker is definitely a real XML editor, because it can open, edit, and save XML files.

I hear people say that FrameMaker’s not a real XML editor because it uses a proprietary binary format and you can’t edit the XML tags directly. The truth is that all XML editors convert the XML on disk to some internal binary format while the file is open for editing. That’s how you get that nice tag coloring and fonts. Just because the XML you’re editing looks like the XML you think is in the file, that’s just eyewash. Granted, FrameMaker doesn’t let you edit the XML structure by entering tag names in angle-bracketed code, but that doesn’t change the fact that you are editing the same XML structure that you would with any other XML editor. It’s just a different rendering of the XML on disk than you’ll see in other tools. (It would be nice if FM provided a “code view” .. I hope that’s added in the future.)

FrameMaker does provide a number of views into the structure of the XML. It offers a “structure view” which is a collapsible tree of element nodes, allowing you to easily modify attribute values and rearrange the elements by dragging and dropping the nodes into new locations. It also offers a “tags view” which lets you see the element boundaries and their names in the content authoring window (similar to a code view, but you can’t actually edit the tags directly).

FrameMaker is actually one of the oldest XML editors on the market. There are valid reasons to use an XML editor other than FrameMaker, but the issue of it not being a “real XML editor” is not one of them.

Creating New Files in DITA-FMx 1.1

DITA-FMx offers some features that make new file creation simple and easy. Entering the title for the new topic in the New File dialog box automatically creates the file name based on a format that you have defined using special building blocks. You can also create new files using “element templates” which pre-populate the topic with boilerplate content that you have set up. Prolog metadata in new files can automatically be set with the author’s name and creation date, and each time you update a file, the revision date metadata can be automatically set.

This video introduces these and other features for creating new DITA files with DITA-FMx.

If you’re a new user of DITA-FMx or are considering a purchase, you should review this video.

» Link to video on YouTube.

Overview of the Map Authoring Features in DITA-FMx 1.1

DITA-FMx 1.1 provides a number of authoring features not available in standard FrameMaker 8 or 9. Some of these features are not available in other DITA editors, and are typically found only with a content management system. This video provides a quick tour of those features.

If you’re a new user of DITA-FMx or are considering a purchase, you should review this video.

» Link to video on YouTube.

DITA-FMx: Cloning the Default Structure Applications

If you’re using DITA-FMx and would like to modify the formatting and layout in the topic authoring view or for book publishing, you’ll need to modify the corresponding FrameMaker structure applications (Topic, Map, and Book). When it comes time to customize the structure apps, you should “clone” the default applications provided with DITA-FMx to create your own applications rather than modifying the default apps. This video walks you through each step of this process.

This is a fairly complex topic involving the modification of the structure application definition file (structapps.fm) as well as the structure application’s EDD and template files. If you’re just starting out, it’s probably best to work with the default applications for some time before worrying about any customizations.

» Link to video on YouTube.

Installing DITA-FMx 1.1

This video walks you through the complete process of installing DITA-FMx in FrameMaker. It also demonstrates the installation of the default structure applications and creation of a new DITA topic.

This video is useful for those who’d like a quick overview of the installation process. It also shows you the easy way to install new structure applications.

» Link to video on YouTube.