FrameMaker 7.0 Tutorial:
Structured Documents

This tutorial is provided for advanced documentation students on a free, as-is basis, without guarantee of accuracy. If you find any errors or think we should include other tasks, let us know!

This tutorial discusses the following topics:

• About Structured Documents
• Changing the Product Interface
• Creating a Structured Document using a Standard Template
• Opening the Structure View
• Displaying Element Boundaries as Tags
• Inserting Elements and Attributes
• Validating a Structured Document
• Saving a Structured Document as an XML file
• Additional Resources

Subsequent tutorials focus on tags, tables, anchored frames, graphics, templates, master pages, reference pages, cross-references, tables of contents, indexes, variable text, book building, and conversion techniques. These tutorials provide an overview of each topic discussed. If you required information about advanced FrameMaker topics, refer to the Adobe FrameMaker User Guide or Adobe FrameMaker Classroom in a Book for the current version of FrameMaker.

Note: For the sake of brevity, we use an abbreviated style for menu commands throughout this lesson. For example, "Select File > New" means "Select New from the File menu."

A structured document is a document that can be viewed in several ways: as an author, a publisher, or a viewer. SGML, XML, and HTML are examples of structured documents. XML is used in this tutorial to demonstrate the Structured FrameMaker feature.

Structured documents, such as XML files, are created using elements. When working with XML files, the element definitions and structural information is stored in a Document Type Definition (DTD). When working with structured document in FrameMaker, the element definitions and structural information is stored in an Element Definitions Document (EDD). The EDD also contains formatting and style information. When you create a structured document in FrameMaker, you must associate an EDD to the document. The EDD is usually created by an application developer and is outside the scope of this document; for more information about creating EDDs, refer to the Structured FrameMaker Developer's Guide that is distributed with FrameMaker.

This tutorial provides instructions for creating structured documents, inserting elements, adding information to a structured document, and saving a structured document as an XML file.

Changing the Product Interface

1. Open FrameMaker.
   
   
2. Select File > Preferences > General.
   
   The Preferences dialog box appears.
   
   
   
3. From the Product Interface pull-down menu, select Structured FrameMaker.
   
   
4. Click Set.
   
   
5. Close and restart FrameMaker.

Creating a Structured Document using a Standard Template

You cannot create a new structured document within FrameMaker without first creating an EDD. EDDs are usually created by an application developer and are outside the scope of this tutorial. For more information about creating EDDs, refer to Structure Document Developer's Guide that ships with FrameMaker 7.0.

To create a structured document using a template:

1. Select File > New > Document.
   
   
2. Change to the Templates/Structured folder within the FrameMaker 7.0 directory.
   
   
3. Select StrucBody.fm, and click New. The new document appears in the document window.
   
   
4. Select File > Save to save your document.
   

Opening the Structure View

The Structure View provides a hierarchical representation of the document structure and shows the relationship of the elements that are currently used in the document.

To open the Structure View dialog box, click located on the right side of the document window.

The Structure View dialog box appears.

Tip: You can click the minus sign (-) to collapse elements and the plus sign (+) to expand elements. You can also move elements by selecting them and dragging them to a new location.

Opening the Element Catalog

The Element Catalog provides a list of all elements that are available for use within the structured document.

To open the Element Catalog and display all elements:

1. Click located on the right side of the document window.
   
   The Elements dialog box appears.
   
   
   The Element Catalog contains the elements that are available for this document. Initially, the only elements that appear in the Element Catalog are the elements that can be inserted into the area in which the cursor is currently placed.
   
   
2. If you want to view all elements for the document, click Options located at the bottom of the Element Catalog.
   
   The Set Available Elements dialog box appears.
   
   
   
3. Select All Elements, and then click Set.

All elements for the current document are displayed in the Element Catalog.

Displaying Element Boundaries as Tags

To display element tags:

1. Place your cursor within the structured document.

2. Select View > Element Boundaries (as Tags).
   
   The element tags appear in the document window.
   
   
   
   
3. Place your cursor within various parts of the document.
   
   Notice that the list of valid elements within the Element Catalog change according to the location of your cursor. These elements are indicated by a check mark.

Inserting Elements and Attributes

When you place your cursor within the tags of a structured document, the list of valid elements change. These elements are displayed with a check mark within the Element Catalog. If you insert an element that is not valid, your document is no longer structured.

To insert elements:

1. Place your cursor between and .
   
   
2. From the Element Catalog, select QApair, and click Insert.
   
   The Attributes for New Element dialog box appears.
   
   
   
3. In the Attribute Value list, highlight <no value>, and type 04142004.
   
   

   Tip: Although this attribute is optional (see Type: Optional Unique ID in previous dialog box), it is good pratice to use the attribute value within a structured document. You can use this value to identify the segment of text when searching large documents.

   
   
4. Click Insert Element.
   
   New element tags appear in the document window, and your cursor is automatically placed within the tags.
   
   
5. Within the new element tags, type What is the answer?
   
   
6. Place your cursor between and .
   
   
7. From the Element Catalog, select Answer, and click Insert.
   
   New element tags appear in the document window, and your cursor is automatically placed within the tags.
   
   
8. Type The answer is 42.
   
   Your document should look similar to the following.
   

Validating a Structured Document

To verify the structure of your document, you must validate it. Validating your document ensures that all constraints defined for your document have been met. A document is not structured if does not pass validation.

To validate a structured document:

1. Select Element > Validate.
   
   The Element Validation dialog box appears.
   
   
   
2. From the Scope area, select Entire Document.
   
   
3. Click Start Validating.
   
   Within the Element Validation dialog box, notice the error message that is returned.
   
   
   Within the document window, the cursor is placed at the point where the error occurs, and within the Structure View, a red box and an arrow appear at the point where the error occurs.
   
   
   
   To make this document valid, elements must be added before the Heading1 tag.
   
   
4. Within the document window, make sure your cursor is placed before the Heading1 tag.
   
   
5. From the Element Catalog, double-click MenuBar.
   
   
6. Double-click Menu, and then double-click CrossRef.
   
   The Cross-Reference dialog box appears.
   
   
   
7. From the Element Tags list, select QApair.
   
   
8. From the Element (in Document Order) list, select What is the answer?
   
   
9. Click Insert. Your final document should look similar to the following.
   
   
   
10. Validate the document again by following the previous steps.

You should receive the following message indicating that your document is valid.

Saving a Structured Document as an XML file

The best way to save a structured document as an XML file using FrameMaker is to export the file into WebWorks Publisher Standard Edition. This application is shipped with FrameMaker, but installed separately. You must have WebWorks Publisher installed to complete this procedure.

To save a structured document as an XML file using WebWorks Publisher Standard Edition:

1. With your document open, select File > WebWorks Publisher Standard Edition.
   
   The Project Launcher dialog box appears.
   
   
   
2. From the Create a New Project area, select XML +CSS Standard Edition from the Using an existing WebWorks Publisher Project or Template pull-down menu.
   
   
3. Click OK.
   
   The New Project Wizard dialog box appears.
   
   
   
4. In the Please choose a name for this project box, type a name for the project.
   
   
5. Click Next.
   
   
   
   
6. Click Browse, and locate the file to convert.
   
   
7. Click Next.
   
   
   
   

   Tip: You can change the default mappings by selecting a row and then selecting a value from the pull-down menu. For this procedure, the default settings are used.

   
   
8. Click Next, and then click Finish.
   
   A project window appears.
   
   
9. Within the project window, click the plus sign (+) next to your FrameMaker document.
   
   An XML file appears beneath your FrameMaker document.
   
   
   
10. Double-click the file to display it in a browser window.

Additional Resources

For more information about topics discussed in this tutorial, refer to

• WebWorks Publisher Standard Edition product documentation
• Structured Document Developer's Guide (located in the FrameMaker 7.0 directory)

Information and programs provided by hcexres@io.com.