The FrameMaker document model
Like any publishing tool, FrameMaker has layout limitations. If your structure does not match the default FrameMaker document model, you may be able to customize FrameMaker (see FrameMaker customization), but expect implementation costs to skyrocket.
Tables
FrameMaker has a very powerful, flexible table editing feature. XML, however, has no limitations whatsoever on the table structures. Some of the FrameMaker requirements include the following:
- A table cannot occur inside another table.
- Each row in a table must have the same number of columns. You cannot create an irregular table, except by straddling cells.
- Tables are always defined row by row, never column by column.
- Each table can have only one table body section.
Out of the box, FrameMaker supports the CALS table model, a standard for structured tables. If your tables are set up using CALS structure, you should be able to process them successfully, subject to the limitations described here. For more details about how FrameMaker handles CALS tables by default, refer to Appendix A of the Structure Applications Developer’s Guide, an online manual that is installed with FrameMaker.
Object elements
XML does not make any distinction between block elements (paragraphs), inline elements (text ranges), graphic elements, and so on. In FrameMaker, your structure definitions must specify the type of element being created. For example, you must explicitly specify that the CrossRef element is a cross-reference object. See Figure 10.
Most elements are container elements. A container element is an element that allows text or additional elements inside the element. Container elements are used for paragraphs, text ranges, and grouping elements (which may not contain text but do have child elements). For tables, FrameMaker provides additional specialized container element types.
The elements that require special handling are:
- System variables
- Cross-references
- Table components: table, table heading, table body, table footing, table row, table cell, and table title
- Rubi groups (used mainly in Japanese publishing)
- Markers
- Graphics
- Equations
FrameMaker defines a special class of elements, called object elements, which are not permitted to have child elements or contain text. System variables, cross-references, markers, graphics, and equations are all object elements. Object elements can have associated attributes, but the elements cannot contain child elements or text.
You can work around these limitations by customizing your structured application files, but they do increase the complexity of the implementation. For instance, FrameMaker expects the following structure for an index marker by default:
<IndexEntry text="index entry text"/>
You might, however, have XML where the IndexEntry element has text:
<IndexEntry>index entry text</IndexEntry>
You would need to modify the import process to move the index information from the element text to the attribute text. Furthermore, there is a 255-character limit on marker text in FrameMaker.
The syntax used for index entries with multiple levels may also present challenges. FrameMaker embeds the entire index marker text in a single attribute. Primary and secondary entries are separated with colons; multiple entries use colons, as shown here:
<IndexEntry text=”bear:hibernating;hibernation”/>
If the XML structure uses different indexing syntax, you will need to map it over to conform to FrameMaker’s expectations.
For all object elements, keep in mind that you cannot have child elements inside the object.
Generating unique IDs for elements
ID attributes are commonly used to manage cross-references in structured documents, and FrameMaker supports these IDs. When you insert a cross-reference element and point to another element, FrameMaker automatically creates an Id attribute with a unique value for the target of the reference. The cross-reference element automatically gets an Idref attribute with the same value (Figure 11).
To implement structured cross-references in FrameMaker, you must set up your structured definitions as follows:
- Require an Idref attribute for every element of type cross-reference (Figure 10).
- Permit an Id attribute for any element that could become the target of a cross-reference (Figure 12).
FrameMaker will not automatically assign Id values to elements as you create the elements; Id values are assigned only when the specified element becomes the target of a cross-reference. Once an Id value is assigned, it is reused for any subsequent cross-references.
Generated files
Generated files, such as the table of contents and index, are unstructured in FrameMaker, even if the other files in the book are structured.
You can set the read/write rules to drop the unstructured generated files on export to XML. If you are processing the XML to produce rendered output (such as HTML), you can re-create the table of contents and index from the information present in the XML files (that is, the various title elements for the table of contents and the structured index entry elements for the index).
You can set the read/write rules in the structured application to create a book file and chapter files during importing of XML content. Once the content is in FrameMaker, you create new generated files for the book. You can also write a FrameMaker Developer’s Kit (FDK) client to automatically create the generated files during the import process.
Labeling versioned information with conditional text and attributes
FrameMaker’s conditional text feature gives you the ability to show and hide information based on the condition settings.
In version 7.0 and earlier, shown conditional text in the FrameMaker files is exported to XML, and hidden conditional text is deleted. The resulting XML files do not contain any information about the conditional text labels.
In version 7.1, you can successfully round-trip conditional text information with processing instructions. Figure 13 shows a recipe with two conditions and how that conditional information is maintained with processing instructions in the XML output.
We recommend that you avoid “double-tagging” text with more than one condition if possible; it can make processing the XML very complicated.
Another option for versioning information is to use element attributes. Attributes are better integrated into the structure of the document (Figure 14).
Attributes are easier to process in XML than processing instructions. FrameMaker 8 includes support for attributes, but FrameMaker 7 does not have the functionality to show and hide information based on attribute values. If you use attributes to label information as belonging to different versions, you will need to develop a solution for displaying and printing the different versions of the document. Here are some options:
- If information is being created in XML, preprocess the XML files with an Extensible Stylesheet Language (XSL) script that strips content based on attribute values. For example, if you have an Output attribute, you could remove any material that has the OnlineOnly attribute value before you import the content into FrameMaker for printing.
- Use a third-party plug-in for FrameMaker called Sourcerer, which allows you to show and hide information based on attribute values.
- Use FrameScript or the FDK to enable attribute-based versioning.
- Export FrameMaker files to XML, process them to eliminate information you don’t want, and re-import the processed file for printing.
Element sequence
You can process an XML source document and produce rendered documents (perhaps in HTML) in which information is presented in a different sequence from the original XML file. FrameMaker can interpret and format element information, but as a general rule, the elements need to be in the same order as the page-based presentation. If the element sequence in your source XML files does not match the required sequence, preprocess the XML file to create a file with the needed element order and then import the processed file for printing.
Formatting issues
In the FrameMaker EDD, you use context rules to define formatting for elements. The context rules let you specify that a single element uses different formatting based on its position (context) in the structure (Figure 15).
Context rule syntax lets you check for a particular parent, ancestor, or ancestor sequence and apply formatting based on the match. You can also use sibling rules; for example, a rule applies formatting based on whether the current element is the first sibling. Context rules are more limited than what’s available in the XSL used for processing XML. Context rules do not let you assign formatting based on descendant elements. The sibling rules are also more limited than in XSL.
Next page:
FrameMaker customization