XML with FrameMaker

Create, open, and save XML files

Create an XML file

To create an XML file:

  1. Select New > XML from the File menu. The new XML dialog is displayed as follows:

  2. In the New XML dialog, select one of the following:

    1. Recently used: Displays the types of XML topics you have created recently.

    2. Structured Applications: Displays the structured applications set up on FrameMaker that can create new XML topics, including the DITA topics and S1000D modules

    3. DITA: Displays the available DITA templates.

    4. S1000D: Displays the available S1000D modules.

    5. Other XML: See Create a blank XML document and Create a blank XML document based on a DTD.

  3. Click OK to create the XML file.

Create a blank XML document

  1. In the New XML dialog, select XML Document.

  2. Select Empty XML Document and click OK.

Create a blank XML document based on a DTD

  1. In the New XML dialog, select Other XML.

  2. Select DTD-based XML Document and click OK.

  3. In the Customize XML dialog, specify the following and click OK:

    1. Root element: Based on the DTD, specify a valid root level element for creating your xml document. A DTD may have multiple valid root elements.

    2. Public ID: Optionally, specify a unique public ID for the XML document. A public identifier is a way to specify the DTD an XML document was created under.

      A public id is of the format: prefix//owner-identifier//text-class text-description//language//display version

    3. System ID: Specify the full path of the DTD. A system ID specifies the exact location of the DTD relevant to the document.

Open an XML file

  1. In Structured FrameMaker, choose File > Open.

  2. Select the file you want to open, and click Open.

  3. If the Use Structured Application dialog box appears, choose an application name from the Use Structured Application pop-up menu, and click Set. Then do one of the following:

    • To associate an application with the file, choose the name of an application.

    • To use default mapping and no read/write rules, choose <No Application>. (You may want to use this option to browse a file you don’t intend to save.)

    The WebDAV feature is extended to allow authoring and editing of XML files located on the WebDAV server.

Save an XML file

  • Select File > Save As XML. In the Save Document dialog box, click Save.

  • Select File > Save As. In the Save Document dialog box, select XML in the Save as type list, and click Save.

  • Select File > Workgroup > Save As. In the Save To Server dialog box, select XML in the Format list, and click Save.

FrameMaker saves the file in XML format and preserves the .xml extension.

Save a FrameMaker file as XML

  1. In structured FrameMaker, select File > Save (Or Save As).

  2. Select the folder in which to save the file.

  3. Specify a filename with an .xml extension.

  4. If required, choose XML (*.xml) from the Save As Type pop-up menu.

  5. Click Save.

View XML in Notepad

FrameMaker allows you to view an open XML file in Notepad or in any other text editor that you specify.

To view an XML file:
  1. Open the XML file in FrameMaker.

  2. Click View > View in Notepad. FrameMaker opens the XML file in Notepad.

You can edit the TextEditorPlugin.ini file in the path %AppData%/Adobe/FrameMaker/12 and set the following entries as desired:
  • TextEditorName: Set this entry to the path of your chosen text editor. By default this entry is set to Notepad.

  • SaveFileBeforeOpening: By default this entry is set to No. When this entry is set to Yes, FrameMaker automatically saves the XML file before opening it in Notepad, ensuring that all your changes are in place.

Handling conditional text and XML

Structured FrameMaker allows you to export and import all conditional text (visible and hidden), along with information about the condition tags, such as their show/hide status, color, and style.

To preserve conditional text when saving and opening XML files, the XML file that FrameMaker generates contains the following:

  • Conditional text tags corresponding to the conditional text present in the document.

  • Condition indicators—color and effect— associated with each conditional text tag.

  • The status—show or hide—for each condition tag.

  • Start and end markers for sections corresponding to each tag.

In addition to normal text, support for conditional text in XML allows an entire table or table rows to be conditional. The same applies to footnotes, markers, and anchored graphics. Also, conditional text can be inside a text inset (XML or text).

Handling Whitespace in XML

When you open an XML file in FrameMaker’s WYSIWYG or Author view, the white spaces get normalized according to the White-space normalization standard.

White space in XML is any character from the following set: space, tab and blank line/new line (except hard return). White space serves the following purposes:

  1. Visually format the document in its source form, such as for code, to denote semantic significance for the XML document.

  2. While using a text editor to edit XML, add spaces and line breaks into the element content model for better readability of the XML. This white space is not part of the information conveyed by the document and has no semantic significance for the XML application.

    Note: Default pretty printing is disabled in XML view for new and modified documents.

W3C has defined how white space in XML documents should White-space XML applications.

White-space normalization standard

FrameMaker uses the following rules for white space normalization according to the standard:

  1. XML ignores the first sequence of white space immediately after the opening tag and the last sequence of white space immediately before the closing tag.

  2. XML translates non-space characters (tab and new-line) into a space character and consolidates all multiple space characters into a single space.

  3. XML ignores the sequence of white space occurring between two elements if the parent element is defined to have element content.

  4. You can set the xml:space attribute of an element to preserve to retain the white spaces.For example, if we normalize the following (as appearing in the XML code view):

    Hickory[SPACE][SPACE][SPACE]dikory dock. 
    The mouse[TAB][SPACE]ran up the clock.

    It appears as (in WYSIWYG view):

    Hickory[SPACE]dikory dock. 
    The mouse[SPACE]ran up the clock.
  5. White space introduced through expansion of character references (for example Space =&#32; Tab= &#9; Newline=&#10;) is preserved on XML open. It is not considered white space per the above rules.

    For example, if FrameMaker normalizes the following (as appearing in the XML code view):

    Hickory&#32;&#32;&#32;dikory dock. 
    The mouse&#9;&#32;ran up the clock.

    After normalization, tt appears as the following (in WYSIWYG view):

    Hickory[SPACE][SPACE][SPACE]dikory dock. 
    The mouse[TAB][SPACE]ran up the clock.

Disable dropping whitespaces on import

To disable dropping whitespaces, set the property RemoveExtraWhiteSpacesOnXMLImport in maker.ini to FALSE.
Note: Use caution while editing an ini file.

Preserve whitespaces for specific elements

If the xml:space attribute is set to preserve (xml:space="preserve"), then FrameMaker preserves all whitespaces. You can use this setting to preserve whitespaces for certain elements alone. This setting lets FrameMaker drop whitespaces for all other elements in the WYSIWYG and Author views.

Handling cross-references in XML

Structured FrameMaker allows you to generate and retain external cross-references when saving and opening XML files.

For example, if your FrameMaker file contains a cross-reference to another file, when you save your file in XML, FrameMaker generates tags representing the cross-reference along with information about the referenced file. When opening the same XML file, FrameMaker converts the cross-reference tags and the information they contain into a FrameMaker cross-reference.

FrameMaker supports a new attribute, srcfile, to retain external cross-reference information when generating XML documents.

When you export a file containing an external cross-reference to XML, the srcfile attribute of the cross-reference contains the name of the referenced file and the ID of the referenced element in the file.

Note: FrameMaker converts file paths in the generated XML to URIs.

Using the configuration file editor

Every structured application may include an XML configuration file. The configuration file is optional and contains attributes and their suggested and default values. To call the editor, click Element > Launch Config File Maker... The configuration editor is displayed as follows:

View full size graphic
Configuration file editor

  • To load an existing configuration file, click Load Configuration File and select the file.

  • Set the configuration values as desired. Click the value column of the choice or default to be changed and enter the new value.

  • To insert a new choice, right click the row above which the choice is to be placed, and select Insert Above.

  • To delete a choice, right click the choice and select Delete.

  • To save the configuration, click Save.

  • To save the configuration as a new configuration file, click Save As and enter the new filename.

When opening a structured application, FrameMaker reads the corresponding configuration file (if it exists) and populates the attribute values automatically.

The attribute editor allows you to change these values, when using the structured application.

Using the attribute editor

FrameMaker includes a powerful attribute editor that helps you to edit element attributes easily. To load the editor, click Element > Edit Attributes.... The attribute editor is displayed as follows:

Attribute editor
The editor reads the attributes from the configuration file supplied when creating a structured application.

  • To view just the attributes that are required and specified, click the Required and Specified option.

  • To set a value, click the value column of the selected attribute. Enter the value. The value is set automatically.

  • To delete a value, click the value of the selected attribute and press Delete.

  • To delete all user set values, click Reset All.

  • To restore all values to the defaults specified in the config file, click Restore Defaults.

Options for processing XML

FrameMaker provides options for processing XML. FrameMaker also allows XML import and export to support XSL transformations (see XML with XSL transformation), and the Schema language for grammar and rule definition (see XML with schema). You can import an XML document that uses schema, automatically creating a Document Type Definition (DTD) from the referenced schema, or you can create an Element Definition Document (EDD) directly from a schema definition. This release also enables validation against an associated schema upon both import and export.

XML with XSL transformation

XSL (EXtensible Stylesheet Language) is a style sheet language for XML documents. XSLT (Extensible Stylesheet Language Transformation) is the means by which transformations defined in XSL are applied to XML documents.

XSL is a set of the following three specifications:
XSLT
A language for transforming XML documents.

XPath
A language for navigating in XML documents.

XSL-FO
A language for formatting XML documents.

FrameMaker includes an XSLT processor that allows you to associate an XSLT file with an XML structure application or XML document, and apply the transformations defined in that document when importing from or exporting to XML. FrameMaker supports W3C XSLT 1.0 recommendations. You canUpgrade to Saxon 2.0 processor by editing the maker.ini file.

  • New elements in the structure application (XSLTPreferences in the stylesheets element of XMLApplication) allow you to specify an XSLT file as part of your XML structure application, to be used for both import and export.

  • The xml-stylesheet processing instruction (PI) now allows you to specify an XSL file in an XML markup document, which supersedes any XSLT specified in the structure application when importing that document.

Upon import, XSL transformations are applied before the default read rules or any additional read rules you have defined. That is, the result of applying an XSL transformation on import is a new file, which (if it is an XML file) is passed to the read/write rules.

Upon export, XSL transformations are applied after the default or explicit write rules. The result of applying read/write rules on export is a new XML file, which, if it is valid, is passed to the XSLT processor.

Upgrade to Saxon 2.0 processor

  1. In the maker.in file, locate the XSLTProcessors section.

  2. The entry for the Xalan processor has the suffix: , Default.

    XALAN=fminit\XSLT\XSLTProcessors\xalan\xalan-j_2_7_1-bin\xalan.jar, 
    org.apache.xalan.processor.TransformerFactoryImpl, Default 
    SAXON=fminit\XSLT\XSLTProcessors\saxon\saxonhe9-3-0-5j\saxon9he.jar, 
    net.sf.saxon.TransformerFactoryImpl
  3. Cut and paste to shift the suffix to the Saxon processor’s entry as following:

    SAXON=fminit\XSLT\XSLTProcessors\saxon\saxonhe9-3-0-5j\saxon9he.jar, 
    net.sf.saxon.TransformerFactoryImpl, Default

XML with Cascading Style Sheets

When an XML document is opened in FrameMaker, FrameMaker processes CSS2 by mapping the CSS information to appropriate EDD rules in the EDD document.

The following scenarios describe the processing of CSS2 in FrameMaker:

  • You open an EDD in FrameMaker and use the Import CSS Styles option in the StructureTools menu. FrameMaker checks whether the current document is an EDD. If so, the Open dialog box appears and you can specify the CSS file path. The CSS is then imported into the EDD. You can then import the element definitions from the EDD into a template to use when you open an XML file. If the EDD contains formatting rules, the CSS properties are appended to the existing rules if the properties are unique. Alternatively, the CSS properties you import will overwrite the existing formatting rules of the EDD. You can also export XML style information to an EDD for all elements in a document that use the Cascading Style Sheets 2 (CSS2) format, using the Generate CSS2 option in the StructureTools menu.

  • When you open an XML file that is associated (using xml-style sheet PI) with style sheets, FrameMaker reads the DTD and the style sheet associated with the XML document, and then generates a temporary template to use for opening the XML file. However, if a template is already specified in the “Structured Application” (used to open the XML file), FrameMaker uses that template to open the XML file and will not generate any new template from the DTD and style sheets.

Note: An XML file opened in FrameMaker can contain multiple CSS files. FrameMaker supports the author’s style sheet only, and not the user’s style sheet.

Import CSS element styles into an EDD file

You can import element formatting from CSS into EDD to ensure consistent formatting across different XML applications. The CSS file can be referenced in the XML document or manually imported. Multiple CSS files can be imported sequentially for multi-level formatting.

When importing element styles, FrameMaker retains the context information (element property or selector) from the CSS and imports it into the appropriate EDD contexts.

Note: FrameMaker imports style information only at the element level.

You can also set CSS preferences in XML using Structured FrameMaker. For more information, see the Structured FrameMaker Developer's Guide, located in the Documents folder.

  1. Open the EDD file in structured FrameMaker.

  2. Select StructureTools > Import CSS Styles. The Import CSS dialog box appears.

  3. Select a CSS file, and click Open.

  4. If the Structured Application element in the EDD file doesn’t define an application name, the Use Structured Application dialog box appears. Select the application that was used to create the EDD file. Click Continue.

The CSS file is imported into the EDD file.

Note: If the EDD already contains formatting rules, the CSS properties are appended to the existing rules. If the CSS properties overlap some of the existing rules, the CSS properties replace the existing rules in the EDD. The EDD doesn’t support all properties and selectors defined in CSS 2.0. If a property or selector in the CSS file can’t be mapped to an equivalent EDD rule, that property or selector is ignored. No error is displayed when this happens, and no error log is created.

After importing the CSS styles, you can import element definitions from the EDD into a template and use the template to open an XML file.

As an alternative to the CSS import process, you can use FrameMaker to open an XML file that already has CSS styles associated with it. When you open the XML file, FrameMaker reads the DTD and CSS files and generates a temporary template that is used to open the XML file.

Export CSS for a FrameMaker XML file

You can export XML style information available in your document for all elements using the Cascading Style Sheets 2 (CSS2) format, to an EDD file. You can then import these CSS Style definitions from the EDD file to new XML files. Cascading Style Sheets let authors attach styles, such as fonts and spacing, to structured XML files. CSS2 format is a W3C standard.

When you choose the Generate CSS2 command, styles from well-formed structured documents are generated, based on the formatting information available in the EDD associated with the source document. FrameMaker exports style information only at the element level. For example, if you apply a style to only one particular word in the Text element, that one instance of style is not exported.

You can set CSS 2 preferences in the XML application. For example, you can determine whether the CSS 2 file is automatically generated when you export to XML. For more information, see the online manual, Developing Structured Applications with Adobe FrameMaker on the Adobe website, www.adobe.com/go/lr_FrameMaker_support_en.

  1. Open the template or document with an associated EDD in Structured FrameMaker.

  2. Select StructureTools > Generate CSS2.

XML with schema

FrameMaker allows you to import XML markup documents that are associated with W3C's XML Schema language. FrameMaker automatically creates a DTD and EDD from the schema. FrameMaker validates the document structure against the associated schema upon both import and export to XML, but does not retain all schema information upon export.

For complete details of how schema is mapped to DTD, see the Structure Application Developer’s Guide.

Note: This release offers support for schema that is equivalent to what was previously available for DTD. That is, EDD has not been extended to accommodate features in schema that are not available in DTD. For this reason, schemas are read-only, and you cannot export the EDD back out to schema.

Schema workflow

You can import an XML document that references a schema file, and you can specify a schema file in your structure application, to use for validating a document upon export to XML.

  1. For a specific XML document, you can include the path of the schema file in the XML using attributes - noNamespaceSchemaLocation or schemaLocation depending on whether your schema includes a target namespace or not.

  2. To specify a schema file for use in exporting XML, modify the structapps.fm file. Use the Schema element as part of the XMLApplication to provide the schema file path for export.

  3. Open the XML in Frame using a structured application. Edit it.

  4. Save the XML using a structured application. The Schema element in the structapps.fm file is output in the file and validation is performed against it.

In this workflow, a DTD is generated automatically as an intermediary file from the schema given in the XML document, and you do not modify it. However, you can also use a schema file to generate an EDD; see Generate an element catalog (EDD) from a schema.

Changes to the structure application for schema support

The new element Schema, a child of the XmlApplication element, specifies the path of a schema file in the structapps.fm structure application file. If instance documents use namespaces, the property Namespace in XmlApplication must be set to true.

In order for a structure application to be selectable in the Use Structured Application list while importing a document that is associated with a schema, the schema’s root element must be included in the application’s DOCTYPE in the XmlApplication element.

Generate an element catalog (EDD) from a schema

You can create an EDD from a schema definition, or import the elements from a schema definition into an existing EDD. FrameMaker converts the schema definition to DTD first, and then creates or imports elements to an EDD.

Use the following commands in the StructureTools menu:

  • Open schema: This command converts a specified schema to DTD, and creates an EDD from the DTD.

  • Import schema: This command converts a specified schema to DTD, and imports elements from the DTD into an existing EDD.

Each command opens a File Choose dialog box that allows you to specify the schema file, then a Save dialog box in which you specify where to save the resulting DTD file.

  1. In Structured FrameMaker, select StructureTools > Open Schema.

  2. Choose a schema file.

  3. Choose a path for the DTD to be output.

  4. Examine the resulting DTD and make any modification you want.

  5. Create an EDD from the generated DTD, as described in the Structure Application Developer’s Guide.

  6. Use this EDD to create a template that can be included in the Structured Application.

  7. Provide your DTD path along with the Schema Location in the input XML. This will make sure that FrameMaker works correctly with your template. Validation of input and output XML is still performed against the schema.

View or edit XML namespaces

An XML namespace is a collection of names for specific element types and attribute names within an XML document. The scope of a namespace extends beyond its containing document.

Because a single XML document can contain elements and attributes that can be used by multiple software applications, you can use namespaces to differentiate which elements and attributes are to be used by which applications. Software applications that process XML use namespaces to recognize which tags and attributes they are designed to process.

Names from XML namespaces may appear as qualified names, which contain a single colon, separating the name into a namespace prefix and a local part. The prefix, which is mapped to a Uniform Resource Identifier (URI) reference, selects a namespace. The combination of the universally managed URI namespace and the document's own namespace produces identifiers that are universally unique.

Using XML namespaces in FrameMaker

FrameMaker supports namespace usage for all elements in an XML document. When you import an XML document containing namespaces, all namespace information is preserved.

You can view, edit, add, or delete namespaces to an XML document in Structured FrameMaker using the Namespaces command. You can also use this command to view the definition of the prefix on an element tag and select the element that defines the prefix.

By default, namespaces in FrameMaker are handled as namespaces, appearing in the Namespaces dialog box. However, you can disable namespaces in the application and have them handled as attributes instead, appearing in the Structure View.

  1. Open the document in Structured FrameMaker.

  2. Select an element in the Structure View.

    Note: Elements that contain namespaces appear in Structure View with an asterisk (*) next to their names.
  3. Choose Element > Namespaces.

  4. In the Namespaces dialog box, click Select Defining Element to view the namespace for the selected element in the Structure View.

  5. Make any desired changes to the Declared Namespaces, Prefix, or Path and then click Add, Change, or Delete. To close without saving your changes, close the dialog box without clicking an option.