Find and correct errors in document structure

Use the Structure View to find errors

Understand how to use the Structure View to find and correct errors in the document structure with Adobe FrameMaker.

When an element doesn’t conform to content rules and attribute descriptions in the document’s element definitions, the Structure View identifies the error for you.

Missing elements: If an element is missing one or more child elements required by the element definitions, a small red hole appears on the vertical line where the child element should be.

Figure 1. At least one required child element is missing.
Elements at an invalid location: If an element is at a location not allowed by the content rules, the vertical line next to it is broken from the position of that element to the end of the parent element.

Figure 2. The Para element is invalid at this location.
Undefined elements: If an element is not defined for the document, its bubble is red. This sometimes happens if you have pasted the element from another document.
Invalid attributes: If an attribute has an invalid value or is not defined for the document, it appears with a red x to the left of the attribute name and its value is red.

Figure 3. The DraftVersion attribute is invalid
Attributes missing a required value: If an attribute does not have a value, no value appears to the right of the attribute name. If the attribute requires a value, no value is red and a red hole appears to the left of it.

Figure 4. The XRefLabel attribute is missing a required value.

Validate a document

Understand how to validate a document and correct errors in the document structure with Adobe FrameMaker.

Introduction

When FrameMaker validates a document, it searches for elements that do not conform to content and attribute rules in the document’s element definitions. If FrameMaker finds an error, it selects the element and describes the error.

You can validate an entire document, the current flow, or the current element. If you validate the current element, FrameMaker does not check the descendants of the element’s child elements. For example, if you validate the <Section> element below, FrameMaker makes sure that the <Head> element, the two <Para> elements, and the <List> element are valid, but does not check the <List Item> elements in <List>.

Figure 5. Only the section’s child elements are validated

Validated child elements of a section in the Structure View

If the document has conditional text, only the versions that are showing are validated.

You can also validate an entire book including all its files, only the book file, or only the current element in the book file.

How to validate a document

To validate a document, do the following:

Choose Structure > Validate. The Element Validation dialog is displayed:

Figure 6. Element Validation dialog
Select Entire Document/Book, Book Elements Only, Current Flow, or Current Element to specify the scope of the validation.
To exclude missing elements or attribute values from the search, select Ignore Missing Elements or Ignore Missing Attribute Values.

If these settings are selected, FrameMaker does not look for places where a required child element or a required attribute value is missing. Consider selecting these if you are not trying to build a complete document yet.
Click Start Validating.

FrameMaker starts checking at the beginning of the current element. If you’re validating only the current element, it checks the element with the insertion point or the selected element. If more than one element is selected, it checks the first element in the selection.
If FrameMaker finds an error, click Start Validating again when you’re ready to continue validating.

The top of the Element Validation dialog box shows the name of the element and a brief message about the problem.

You can correct the error, ignore it, or click Allow As Special Case. If you mark it as a special case, FrameMaker won’t identify the error the next time you validate the document.
Repeat step 5 until FrameMaker does not find any more errors.

When FrameMaker reaches the end of the document, it returns to the beginning and continues validating. When FrameMaker reaches the end of a flow, it continues to the next one.

Note: When validating a book, FrameMaker tells you if a file in the book has invalid content, but for a more detailed evaluation, you must open and validate the file.

Validation of the elements in an EDD includes attributes in if-then clauses. For example, suppose that the possible values of an attribute are A or B or C, and a context rule says If [attrval = "D"]. This is flagged as an error and reported as an invalid structure when the element definitions are imported.

Similarly, if an element’s text formatting rules or prefix/suffix rules use attribute names in the context specifications, the attribute name and case must match the attribute definition in the element’s definition.

If an attribute’s value is changed to the same value it previously had, the action is not flagged as a change. This enhances performance by eliminating unnecessary value checking.

Clear all special cases

Choose Structure > Validate.
Click Clear Special Cases. FrameMaker clears the special cases in the document, the flow, or the element—whichever scope is selected in the dialog box.

Validation error messages

Understand the validation error messages when validating a structured document with Adobe FrameMaker.

The following error messages can appear at the top of the Element Validation dialog in Adobe FrameMaker.

Current flow is unstructured

The current flow does not have elements in it.

Element is undefined

The element is not defined in the document. You perhaps copied this element from another document.

Missing element before <element>

At least one required element is missing before the specified element.

More contents required at end

At least one more child element is required at the end of the current element.

No current element

There is no insertion point or selection.

This message appears when the scope is set to Current Element.

No current flow

There is no insertion point or selection.

This message appears when the scope is set to Current Flow.

Not highest-level element

The element is not permitted at the highest level in the document.

<TEXT> not permitted in this element

The element contains text, but text is not allowed.

<TEXT> not valid at this position

The element is allowed to have text but not at this location.

The @attribute refers to an undefined ID value

The attribute is an ID Reference and refers to a Unique ID value that doesn’t exist in the document (or in the book, if you’re validating a book).

The @attribute is undefined for this element

The definition of this element does not include this @attribute.

This element should be a type

The element is the wrong type, where type can be graphic, marker, cross-reference, equation, or system variable. For example, a cross-reference element sometimes consists of text instead of a cross-reference.

Value must be a type for @attribute

The attribute value is the wrong type for the attribute.

Value for @attribute must be in the range from n to n

The attribute’s numeric value is out of the specified range.

Value for @attribute is not one of the allowed choices

The attribute’s value must match a value from the drop-down list of valid choices.

Value for name attribute must be unique

A Unique ID value must be unique for all elements in the document or book.

Value required for name attribute

The attribute does not have a required value.

<element> excluded in this element

The <element> is not allowed because of an exclusion rule for the parent or one of its ancestors.

<element> not permitted in this element

The <element> is not allowed anywhere in the parent element.

<element> not valid at this position

The <element> is allowed in the parent element but not at the current location.

Correct errors in elements

Learn how to fix XML validation error messages with Adobe FrameMaker.

After you have identified errors in elements and attributes, use the Elements catalog and Structure View as guides for correcting them:

To correct an element in an invalid location, move the element to a valid location, or change it to an element that is valid for its current location.

You can select an invalid element in the Structure View. If you are validating, FrameMaker selects the element for you.

When the element is selected, the Elements catalog shows which elements are valid at that location.

Figure 7. li (List Item) is valid at this location
To correct an element with invalid contents (with the text snippet INVALID CONTENT), change it to an element that allows those contents.
To correct a structure with a missing child element, insert the required element.

You can click where an element is missing, or if you’re validating, FrameMaker places the insertion point there for you. When the insertion point is at the location of the missing element, the Elements catalog shows which elements are valid at that location.

Figure 8. Elements Catalog showing the valid element to enter at a location
To correct an invalid attribute value, change the value to one that is valid for the attribute.
To remove an undefined attribute, select the element with the undefined attribute, open the Attributes dialog box, select the attribute, and click Delete Attribute. In the next dialog box that appears, remove the attribute for the current element or for all elements that have the attribute.
To resolve a cross-reference with an invalid ID, select the cross-reference, choose Insert > Cross-Reference, and change to a source that has a valid ID.