Working with elements in structured documents

The basic unit of information in structured documents is called an element. Elements hold other elements, text, graphics, tables, cross-references, and markers.

You can add elements to a document to build its structure, and you can edit existing elements in many ways.

If you create a FrameMaker document by opening a structured file, you do not need to add elements to it. The document already contains elements. You can edit the document’s elements, and add more elements.

To build a document’s structure, you can either add elements to the document and then fill in the contents, or select existing contents and wrap them in elements.

A structured document has element definitions stored in its Element Catalog. These definitions describe the allowable contents for each type of element the document can have. They sometimes specify attributes and formatting for the elements. If all the elements in a document have contents and attributes that meet these specifications, the document is valid.

Valid contents for elements

An element’s definition has content rules that determine what the element can contain. For example, perhaps the definition of a Section element specifies that a Section must begin with a Head element, then must have a Para element, and then can have any combination of Para, Figure, and other Section elements. A Para element sometimes allows text and CrossRef elements, in any order.

The Element Catalog indicates valid elements for the current location with a heavy check mark. It shows that text is allowed with the <TEXT> tag.

Two classes of elements

Elements fall into two basic classes determined by their allowable contents:

A container element can hold text, other elements, or both. Container elements, such as heads and paragraphs, build the document’s structure.

An object element is a single object—a marker, cross-reference, system variable, equation, or anchored frame. You cannot type in these elements or add child elements to them.

sa_02.png

 

A. Containers have round-cornered bubbles. B. Object elements have square-cornered bubbles.

A container element can be defined to remain empty. For example, perhaps a table cell is empty as part of a table’s design. If an element contains only spaces or non-printable characters such as tabs, its text snippet in the Structure View is <WHITESPACE>.

Attributes for elements

An element can have attributes, which provide information about the element that is not part of the element’s contents. Your document uses attributes for several purposes:

To control the formatting of an element. For example, perhaps a Type attribute in a List element has two possible values—Bulleted and Numbered.

Attributes can provide formatting information.

sa_05.png

To record descriptive information about an element, such as level of classification. An attribute value can even trigger a custom routine that hides the element when the document is displayed.

To store source and destination information for elements, typically for cross-referencing. A Section element sometimes has an ID attribute that stores a unique value. A cross-reference element that points to the Section stores the same value in a Reference attribute, to maintain the connection between the elements.

You typically enter and edit the values for attributes, unless the attributes are defined to be read-only. Cross-reference IDs are often read-only and are generated by FrameMaker.

Import element definitions

If you’re not sure whether a document has element definitions, open the Element Catalog and click in a text flow. If you see elements in the catalog, the document has definitions. You sometimes must select the All Elements option to get elements to appear. Select Element > Set Available Elements for the All Elements option.

If you are using a structured template, then element definitions are usually defined in it. However, sometimes your application developer may provide you with an EDD or DTD that you can directly import into your documents.

1)Open the template, EDD, or DTD with the element definitions. The template, EDD, or DTD must be named and saved.

2)Create a blank document or open the document or book that you want to update. If a book window is active, select the documents you want to update.

3)In the document or book you’re updating, choose File > Import > Element Definitions.

4)Choose the template, EDD, or DTD from the Import From Document pop-up menu. The pop-up menu lists all open and named documents.

5)To remove special formatting and book-related changes in the document, do the following:

To remove format rule overrides, select While Updating, Remove Format Rule Over­rides. Use this setting if you have made text or paragraph formatting changes to elements and now want to return to the formatting described in the EDD or DTD.

To remove element information derived from a book file, select While Updating, Remove Information Inherited from Book. Use this setting if the document used to be included in a book but is now a stand-alone document.

6)Click Import. FrameMaker adds the element definitions to the document’s Element Catalog, replacing existing definitions.

Insert elements

To add an element to a document, you either insert an empty element and enter contents, or wrap an element around existing contents. Before you can begin, your document must have element defi­nitions in its Element Catalog.

If you haven’t yet fully planned your document, consider inserting just the high-level elements, such as Section and Head elements, and then use this structure as an outline for developing the document.

You can also enter all the elements in their correct order and hierarchy as you go, or concentrate on contents rather than on structure, and then validate later to correct errors.

The Element Catalog shows the elements that are available at the current location. You can change the scope of elements available—for example, to show elements that are not valid at the current loca­tion. Ask your application developer for a summary of what each element can contain.

If you have turned on element boundaries, then once you insert or wrap an element, a pair of element boundaries appears in the document window, and a new bubble appears in the Structure View.

Empty element boundaries (left) and bubble for the new element (right)

sa_08.png
Insert an element using the Element Catalog

1)If the document does not have element definitions, import the definitions from a structured template, EDD, or a DTD.

2)Specify the scope of elements available.

3)Click where you want to insert the element. If you’re inserting it between other elements, work in the Structure View rather than the document window.

4)Select an element tag in the Element Catalog, and click Insert. If only one element appears in the catalog, you can click Insert without selecting it.

You can also double-click an element tag to insert the element.

note:    The Element Catalog always displays only those elements that are valid at the insertion point.

5)If the Attributes For New Element dialog box appears, enter attribute values for the element and click Insert Element.

This dialog box appears only if the element has attributes and if an option is set in the New Element Options dialog box to prompt for attribute values when you insert new elements.

6)If you insert a table, a marker, a graphic, or a cross-reference, provide more information about the element in the dialog box that appears.

7)Add content to the elements. You can add content as you insert elements, or after you build the structure of your document.

Press Return to insert elements

In many cases, pressing Return inserts an element automatically. Whenever you press Return, FrameMaker checks the current element’s definition for the following conditions—in the following order—and sometimes inserts a child element:

One valid element

If only one child element is valid at the current location, pressing Return adds that element. For example, after you add a Section, perhaps a Head is the only element permitted next. You can also use this technique to create repeating elements, such as body paragraphs and list items.

More than one valid element

If more than one child element is valid, pressing Return highlights the Tag area to prompt you for an element tag. Type until the tag you want appears, and then press Return to insert the element.

End of an element

If the insertion point is at the end of an element and no more child elements are valid, pressing Return looks for valid elements in ancestors after this location. If a valid element is found, the insertion point moves to the ancestor and the element is inserted (if only one is valid) or the Tag area is highlighted (if more than one element is valid).

Other conditions

If none of the preceding conditions are true, pressing Return causes a beep and no element is inserted.

Set options for inserting new elements

1)Make the appropriate document window or book window active. If a book window is active, select the documents you want to affect.

2)Choose Element > New Element Options.

3)Specify how you want to be prompted for attribute values when you add new elements:

To enter all possible attribute values as you add elements, select Always Prompt for Attri­bute Values.

To enter only required attribute values as you add elements, select Prompt for Required Attribute Values.

To enter attribute values after adding elements, select Do Not Prompt for Attribute Values.

4)To allow FrameMaker to insert child elements automatically for new elements, select Allow Automatic Insertion of Children.

5)Click Set.

tip:   To speed up the process of adding new elements, select the Do Not Prompt for Attribute Values and Allow Automatic Insertion of Children options.

Add text in a structured document

Place the insertion point anywhere inside a text frame in a document window. An insertion point also appears at the corresponding place in the Structure View. To place the insertion point in the middle of text, use the document window rather than the Structure View. When placing the inser­tion point at the beginning or end of an element, or between elements, click in the Structure View.

The Element Catalog describes what the current element can contain. You can enter text whenever <TEXT> appears in the catalog.

1)Place the insertion point:

To place at the beginning or end of text, click to the left or right in the first or second half of the text snippet. After you click, a line on the left or right side of the triangle insertion point indicates that the point is at the beginning or end of text.

To place between two elements, click to the right of the vertical line connecting the elements, between the two bubbles.

Insertion point between two elements

tx_between_elements.png

2)Begin typing. Don’t press Return unless you want to insert a new element, or begin a new para­graph in an unstructured flow.

Edit elements

You can edit a document’s structure in many ways—including changing an element to a different type, rearranging elements, and splitting and merging elements.

After editing one part of a document, sometimes you edit the document further to correct content errors. For example, if you split a Section element in two, you sometimes need to add a Head element for the new second Section. Use the Structure View as a guide for finding errors as you work, or vali­date the document when you’re finished.

Change elements

You can change an existing element to another element of the same type. For example, you some­times want to convert a Para element into a Note element, or a series of Para elements into ListItem elements that you can include within a List element.

However, not all elements can be converted to other elements. For example, if you change a Para element containing text to a Marker element containing the same text, the name of the element changes, but the text is not converted to marker text.

note:   If you want to change contents to a table, use Table > Convert to Table to convert text rather than changing an element.

Changing elements to another type

1)Select the element. You can select more than one element, even if the elements do not have the same tag. All the elements are changed to the new type of element. However, the elements’ chil­dren are not changed, but they sometimes become invalid because the parent changed.

2)Select an element tag in the Element Catalog and click Change. Sometimes attributes in the element become invalid and need to be corrected.

Merge elements

You can merge two or more elements into a single element. Merging places the contents of the second element (including any child elements) at the end of the first element.

Merging two Sections, before and after

sa_13.png

You sometimes must edit the document after merging elements.

note:   If you want to combine table cells, use Table > Straddle rather than merging the cells. You cannot combine other table parts.

1)Select the elements you want to merge. The elements can be of different types, but they must be siblings and next to each other in their parent element.

2)Choose Element > Merge.

Merging retains the attributes for the first element only.

Split an element

You can split an element into two elements that have the same tag and are at the same level. For example, perhaps you split a Section element in two.

Splitting a Section, before and after

sa_14.png

You sometimes must edit the document after splitting an element. In the example above, after split­ting you would add a Head for the new second Section.

note:   You cannot split an element that is a table part (such as a row or cell).

1)Click where you want to split the element. The contents after the insertion point go in the new second element.

2)Choose Element > Split.

Splitting sometimes results in two elements with identical attributes. However, if the original attri­bute had a Unique ID attribute, the second element loses its ID value.

Wrap elements around existing content

You can add structure to content already in a document by wrapping a new element around the content. The content can be any part of a document, including other elements. The element’s content is formatted as specified in the element’s format rules.

note:   You cannot wrap content in elements that are for parts of tables (such as rows or cells), but you can wrap text or other elements that are within a cell or a table title element. If you want to convert text and elements to a table, use Table > Convert to Table rather than wrapping.

After wrapping an element, you sometimes must edit the document to correct structure errors. For example, if you wrap Para elements in a Section element that requires a Head element, you’ll need to insert the Head element.

Wrap an element using the Element Catalog

1)Select the contents you want to wrap in an element. If you’re selecting text, use the document window. If you’re selecting entire elements, use the Structure View.

2)Select an element tag in the Element Catalog, and click Wrap.

3)If the Attributes For New Element dialog box appears, enter attribute values for the element and click Insert Element.

This dialog box appears only if the element has attributes and if an option is set in the New Element Options dialog box to prompt for attribute values when you insert elements.

Wrap elements throughout a document

1)In the document window, wrap text ranges, system variables, and other items that are inside paragraphs. Don’t worry about errors you see in the Structure View. You’ll correct many of these errors when you wrap the lowest levels in parent elements. You can correct the other errors when you’re finished.

2)Wrap paragraphs, headings, and other paragraph-level items in their elements.

3)In the Structure View, wrap the elements you have so far in parent elements, such as Section and List.

Wrapping helps in manually providing a structure to an existing unstructured document. When you wrap the first element in the document, the Structure View immediately changes to show a default invalid structure, as follows:

A highest-level element is added with the tag NoName, unless you begin by wrapping the contents in a valid highest-level element. NoName is a placeholder for your valid highest-level element.

All tables become structured and are given default element tags, such as TABLE and ROW.

Objects become elements with default tags such as CROSSREF, GRAPHIC, and EQUATION.

Footnotes become FOOTNOTE.

Rubi text becomes RUBI and RUBIGRP elements.

note:   Variables and markers do not become structured object elements.

You can correct the structure of the document when you’re finished wrapping elements.

tip:   If your application developer has set up a conversion table for the document, you can apply the table to wrap elements throughout the document all at one time. This is much faster than wrapping text manually.

Unwrapping the contents of elements

Unwrapping deletes an element but leaves its contents in the same place in the document. You usually unwrap elements as part of a larger editing process. For example, if you plan to convert ListItem elements into Para elements, sometimes you must unwrap the parent List element first. Then use Edit > Find/Change to convert the ListItem elements to Para elements.

Unwrapping ListItems, before and after

sa_15.png

You sometimes must edit the document after unwrapping an element. For this example, you would change the ListItem elements to valid elements or rewrap them.

note:   You cannot unwrap an element that is a table part (such as a row or cell).

1)Select the element with the contents you want to unwrap.

2)Choose Element > Unwrap.

Move or copy elements

You can move an element to another location in a document by dragging its bubble in the Structure View. When you move or copy an element, its contents, including descendants, all move along with it. This does not affect the contents of the clipboard.

tip:   If you’re moving an element that has many descendants, collapse the element first. In Structure View, Shift-click an element to collapse/expand all its sibling elements. Alt-click an element to expand or collapse its child elements.

You can also move or copy an element by cutting or copying it to the clipboard and pasting it in a new location, even across documents. If you paste an element from another document, sometimes the element is not defined in your document. If you don’t plan to add a definition for the element, change the element to a valid one. You cannot cut and paste elements in a book file.

1)Do one of the following:

To move an element, drag the bubble to the location you want.

To copy an element, hold down Alt and drag the bubble to the location.

As you drag the bubble to copy, the pointer changes to a hollow, stacked up-and-down arrow­head, and a horizontal arrow moves to indicate where the copy goes if you release the mouse button.

As you drag the bubble to move, the pointer changes to a solid up-and-down arrowhead, and an arrow moves to indicate where the bubble goes if you release the mouse button.

If the element is valid in the location where the arrow points, a check mark or question mark appears in the bubble.

Nudge an element one place

1)Drag the element’s bubble slightly to one side or up or down. As you drag a small distance, the pointer changes to a single arrow. (If you drag too far, the arrow changes to an up-and-down arrowhead.)

Nudging a List one place, before and after

sa_17b.png

When you release, the element moves one place in the indicated direction, as follows:

Moving an element up places it right above the sibling right before it. Moving an element down places it below the sibling after it.

Moving an element to the left makes it a sibling of its parent. Moving an element to the right makes it a child of the sibling before it.

Hierarchical element insert

Using the Elements quick catalog, you can select and insert multiple levels of elements. When you select an element in the quick catalog, FrameMaker displays the elements available within the selected element.

Hit Enter and use the pointer or the arrow keys (or the pointer) to select a hierarchy of elements that you want to insert. When you hit Enter, if there is only one valid element at the pointer’s position, FrameMaker inserts the element.

Use the following keys to navigate through the hierarchy of elements in quick catalogs:

Key\Key action

Type of navigation\action

Place cursor in an element and hit Enter

Display the quick catalog

Right arrow

Display the elements available within the selected element

Left arrow

Hide one level hierarchy of elements

tab

scroll down

shift+tab

scroll up

Alphabets\combination of alphabets

Type an alphabet or combination of alphabets to select an element. For example, press B to select Body and Type T,O to go to Topic.

The list of elements in the quick catalog appears according to the settings in the Set Available Elements dialog. If Show Element Descriptive Tags is selected, the element tool tips in the catalog display the element descriptions.

Hierarchical element insert takes care of auto insertions for the last selected element in the hierarchy, as specified in the EDD. If there are auto insertion rules in place for elements apart from the last element, they are ignored.

Hierarchical element insert

tx_hierarchical_elements.png

A. Select a hierarchy of elements B. Elements get inserted as a group

Select and edit text

 

Select text in flow

1)To select all the text in a flow, click in the flow and choose Edit > Select All In Flow.

Select text in structured document window

You can select entire elements and any part of the document contents in a document window. A corresponding selection also appears in the Structure View.

If an element has contents, you can select all or part of the contents without selecting the element itself. If an element consists of a single object, such as a graphic or a cross-reference, select the entire element.

When you select an entire element, its contents are selected along with it.

tip:   Work with element boundaries showing, so that you can see the beginning and end of each element. After selecting, check the status bar for the correct tag name of the selection parent element. The tag name appears following the “E:” text.

1)To select text in an element, do one of the following:

To select text without selecting the whole element, drag through the range of text. Be careful not to drag across an element boundary. If you do, you select the entire element.

To select one element, drag from anywhere inside the element to outside one of its element boundaries.

To select more than one elements, drag through the elements. FrameMaker selects each element as you drag across one of its boundaries.

Select element content in Structure View

You can select entire elements or the element contents in the Structure View. A corresponding selec­tion also appears in the document window.

If an element has contents, you can select all of the contents without selecting the element itself. If an element is a single object, such as a graphic or a cross-reference, you select the entire element. (Elements that are allowed contents have round-cornered bubbles; elements that are a single object have square-cornered bubbles.)

When you select an entire element, its contents are selected along with it.

1)To select element content, do one of the following

To select an element, click the middle of its bubble.

To select more than one element, click the first bubble and then Shift-click the other bubbles. You can also drag to the right of the vertical line connecting the elements. Start above the first element you want to select, and drag down to the last element you want to select.

To select contents of an element without descendants but not select the entire element, double-click the text snippet.

To select the contents of an element with descendants but not select the entire element, double-click to the right of the vertical line connecting the first level of descendants.

Remove elements

You can remove any element, with or without its contents. For example, you sometimes want to delete a Section element and its contents, or delete the Section but leave the contents in place, so you can place them in a different element.

For elements that are defined to contain text or other elements, you can also delete the contents and leave the empty element in the document. For elements that are single objects without contents, you must delete the entire element.

To remove an element and its contents, select the element and press Delete.

To remove an element but not its content, select the element and choose Element > Unwrap. FrameMaker reformats the contents based on the new context, if necessary.

To remove the contents of an element but not the element itself, select the contents and press Delete.

To remove an element and its contents and replace it with another element, select the element. Then select the replacement element in the Element Catalog, and click Insert. A new empty element replaces the selected element and its contents.

To remove all elements from a document to base it on paragraph and character formats, choose Special > Remove Structure From Flow. If the document has additional structured flows, repeat this command for each flow.

FrameMaker removes all elements from the current text flow. If the formatting was created or modified by format change lists in the element catalog, the removed elements become format overrides in the document.

note:   To create named formats for each removed element variation and save them in the catalog, use the Create And Apply Formats command.

Assign attribute values

Attributes store supplementary information about an element that does not appear with the contents of the document. You can see attributes and their values in the Structure View.

Attributes in the Structure View

sa_19.png

An attribute’s definition specifies the type of values that are acceptable (such as text or numeric) and sometimes includes a list of possible values or a numeric range.

The definition also determines whether the value is optional, required, or read only. It sometimes provides a default value. You can assign values to an attribute if the attribute is not read only.

If an attribute’s current value does not conform to the specifications in its definition, the attribute is invalid.

note:   FrameMaker can provide the values for ID and ID Reference attributes used in cross-referencing. (These attributes are often defined to be read only.)

Enter attribute values as you insert elements

You enter some attribute values as you insert elements, particularly for required attributes and attri­butes that affect formatting. Optional attributes can perhaps wait for a later pass.

Some font property values used in an element definition document (EDD) require that you use specific units. For example, if the Offset Horizontal value is set as a percentage of an em space, typing 5pt creates an offset of 5 em spaces instead of 5 points.

Do not use multibyte (Asian-language) characters when entering attribute values. Sometimes these characters are not exported to SGML correctly because multibyte characters are not supported in the SGML workflow.

note:   Attribute names support the Unicode text-encoding standard.

1)Make sure you are prompted for attribute values when you insert elements.

2)Insert the element. If attributes are defined for the element, the Attributes For New Element dialog box appears, listing all the attributes (except read-only ones) defined for the element.

3)For each attribute value to provide, select the attribute in the Attribute Name scroll list, enter the value in the Attribute Value box, and click Set Value. If an attribute is required, you must enter a value for the element to be valid.

If an attribute has a set of predefined values, choose from the Attribute Value pop-up menu rather than entering a value.

The value you can enter, such as text or a number, is determined by the attribute’s type.

A description of the selected attribute (its type, whether a value is required, and so on) appears in the dialog box below the Attribute Value area.

4)Click Insert Element.

Enter or edit attribute values for elements already in a document

To change an attribute name rather than a value, use Edit > Find/Change. Sometimes this is neces­sary if you imported element definitions that use different attribute names with identical meanings, such as Security instead of SecurityLevel. The new attribute name must be defined for the element.

1)Select the element with the attribute value you want to change.

You can select more than one element of the same type, and apply the change to all. The elements must be contiguous. For example, if several Para elements in a row have a Security attribute, you can change the value of that attribute for all the Para elements at one time.

2)Double-click an attribute name or value in the Structure View to display the Attributes dialog box.

Alternatively, access the Attributes modal pod from Elements > Edit Attributes.

3)For each attribute value to enter or edit, select the attribute in the Attribute Name scroll list, enter the value in the Attribute Value box, and click Set Value.

If an attribute has a set of predefined values, choose from the Attribute Value pop-up menu rather than entering a value.

4)Click Done.

Auto-generate unique IDs for attributes

FrameMaker allows you to define the elements in your structured application for which you want it to auto-assign unique IDs. For example, say your structured application includes a section element that has an id attribute. You can create configurable rule that ensures that whenever you add the section element to your structured document, FrameMaker will auto-generate a unique ID. FrameMaker will then assign that ID to the id attribute of the section element.

Define the auto-generation rules for a structured application

1)Choose Element > Launch Config File Maker.

2)In the Configuration File Settings dialog, you define the ID generation rules.

ID Prefix

A text and number combination that will be prefixed to the ID that FrameMaker auto-gener­ates.

Assign ID to Attribute

The name of the attribute to which FrameMaker will assign the auto-generated ID.

note:    You can specify any attribute to which FrameMaker will assign the ID.

Choose <auto> to allow FrameMaker to decide to which attribute the ID is assigned.

For Elements

Specify the names of elements to which FrameMaker will assign an ID to the attribute specified in Assign ID to Attribute described above.

note:    The list of Elements will increment as you enter an new element name. This allows you to enter any number of elements to which to assign IDs for the specified attribute.

For Elements having Attributes

You can also choose to specify elements by their attribute values.

This implies that you can define an attribute name to ensure that FrameMaker assigns an ID to any element that contains the specified attribute. For example, you can ensure that Frame­Make will assgin an ID to all elements that have the attribute audience. However, the ID is assigned to the attribute that is specified in the Assign ID to Attribute field described above.

You can also add attribute values to the above attribute rule. For example, you can ensure that FrameMake will assgin an ID to all elements that have the attribute audience and the value admin.

Also, you can specify multiple values and FrameMaker will assign the ID based on any one of the values. For the audience example, you can specify the value as admin or end-user. In this case, the ID is assigned if the element contains the audience attribute and the value of the attri­bute is either admin or end-user.

note:    The Attribute list will increment as you enter an new attribute names.

3)Click Save or Save As to save the ID generation rules to a configuration (.xml) file.

To load the set of rules defined in an existing configuration file, click Load Configuration File.

4)You can then include this configuration file to your structure application.

Types of attributes

An attribute’s type determines the kind of values that are allowed in the attribute. For example, the value version 1 is not valid for an attribute defined as an integer, but the value 1 is valid. Numeric types (such as integer or real number) can also be limited to a predefined range by their attribute definition.

Choice

An attribute with a list of predefined values.

ID Reference

An attribute with a value that is a Unique ID value from another element. It is typically used for element-based cross-references.

ID References

An attribute with a value of one or more Unique ID values from another element. (Sometimes the developer specifies this attribute if you’re exporting to a structured application that uses multiple values for source information.)

Integer

An attribute with a whole number value (no decimal parts). Examples of valid integers are 22, -22, and +322. An integer can be defined to fall within a range.

Integers

An attribute with a value of one or more integers. Enter each number on a separate line in the Attribute Value box.

Real

An attribute with a real number value, with or without a decimal part (the value can also be expressed in scientific notation). Examples of valid real numbers are 2, 22.4, -0.22, and 2.3e-1. A real number can be defined to fall within a range.

Reals

An attribute with a value of one or more real numbers. Enter each number on a separate line in the Attribute Value box.

String

An attribute with a value of a series of characters (text).

Strings

An attribute with a value of one or more strings. Enter each string on a separate line in the Attribute Value box.

Unique ID

An attribute with a value of a unique text string. An element can have only one ID attribute (which can be of type Unique ID or Unique IDs). All ID values must be unique in the docu­ment or book. An element with a Unique ID attribute can be the source for an element-based cross-reference.

Unique IDs

An attribute with a value of one or more unique text strings. Enter each string on a separate line in the Attribute Value box. (Sometimes the developer specifies this attribute if you’re exporting to a structured application that uses multiple values for source information.)

Copy attribute values

You can use the clipboard to copy and paste attribute values from one element to another. If you paste values to an element that does not have corresponding attributes defined, the attributes are invalid. To preserve element-based cross-references, an ID attribute value is not pasted.

If you copy an attribute from another document, the attribute sometimes is not defined in the current document.

1)Select the element with the attribute values you want to copy, and choose Edit > Copy Special > Attribute Values. All attribute values associated with the element are copied to the clipboard.

2)Select a different element and choose Edit > Paste.

3)(Optional) To delete an undefined attribute copied from another document, 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.

Find and edit elements and attributes

You search for elements and attributes in a structured document to keep track of them or to make changes to them quickly. Searching is especially useful when you want to apply the same change to more than one occurrence of an element or attribute.

You can also search for many other items in FrameMaker, including strings of text, specific format­ting, unresolved cross-references, and objects (such as anchored frames) that are not elements.

note:   The Find/Change feature supports the Unicode text-encoding standard.

Search for element tags, attribute names, or attribute values

You can search for an element tag, attribute name, and attribute value either separately or in combi­nation. For example, you can search for an element tagged List to find each List element, or perhaps you limit the search to find only List elements that have a Security attribute set to Classified.

1)Choose Edit > Find/Change.

2)Choose Element from the Find pop-up menu.

3)Select the options you want in the Find Element dialog box.

The settings can be used in many combinations. These are a few examples:

To find any element, leave all three boxes empty.

To find a specific element, type an element tag but leave the Attribute Name and Attri­bute Value boxes empty.

To find any element with a specific attribute, type an attribute name but leave the Element Tag and Attribute Value boxes empty.

To find any element with a specific attribute value, type an attribute value but leave the Element Tag and Attribute Name boxes empty.

To find a specific combination of element and attribute, type an element tag and choose an attribute name.

To find a specific combination of element and attribute value, type an element tag and choose an attribute name and an attribute value. (If the attribute type is Choice, type the value.)

To find a specific element with an attribute that has no value, type an element tag, choose an attribute name, and choose <No Value> from the Attribute Value pop-up menu.

Leave a box empty if you do not want to restrict the search. An empty box has the same effect as searching for any element, or choosing either <Any Attribute> or <Any Value>.

4)Click Set.

5)In the Find/Change dialog box, select Consider Case, Whole Word, Use Wildcards, or Find Backward.

6)Click Find.

note:   After searching the main flow, FrameMaker looks at other text frames and text lines. Because a search is flow by flow, it sometimes appears to jump around the document.

Change elements or attributes you find

After you find an element, attribute, or attribute value, you can change it to another element, attri­bute, or value. For example, you can quickly and globally change the value of a SecurityLevel attri­bute from Declassified to Top Secret.

When changing items in a document, you can change each occurrence of the item as it is found or have FrameMaker automatically make the change throughout the document.

tip:   After pasting material from another document or importing new element definitions, use the Find/Change command to clean up your document. For example, pasting a table from an unstructured document gives the table and its parts default, invalid element tags. You can use Find/Change to change CELL elements, for example, to TableCell elements.

1)Choose Edit > Find/Change.

2)In the Find/Change dialog box, choose Element from the Find pop-up menu.

3)Select the options you want in the Find Element dialog box, and click Set. Then choose an option from the Change pop-up menu in the Find/Change dialog box, and type the replace­ment tag or value.

The Find Element dialog box and the Change pop-up menu work together. These are a few examples of combinations you can use:

To change one element to another, type an element tag in the Find Element dialog box but leave Attribute Name and Attribute Value empty. Then choose Element Tag To in the Change pop-up menu and type an element tag.

To change one attribute to another, type an attribute name but leave Element Tag and Attribute Value empty. Then choose Attribute Name To and type an attribute name that is defined for this element.

To change one attribute value to another, type an attribute value but leave Attribute Name and Attribute Value empty. Then choose Attribute Value To and type a value.

To change an attribute with a specific name to a certain value, type an attribute name but leave Element Tag and Attribute Value empty. Then choose Attribute Value To and type a value.

To change a specific element with a specific attribute value to another element, type an element tag and choose an attribute name and attribute value. Then choose Element Tag To in the Change pop-up menu and type an element tag.

To remove an attribute value, type an attribute value but leave Element Tag and Attribute Name empty. Then choose Attribute Value To and leave the Choose box empty.

If you try to make a change that is not allowed—for example, if you try to remove an element tag—an alert message appears explaining the problem.

4)Click Find.

5)When FrameMaker finds the element or attribute, do one of the following:

To make the change but not continue searching for other occurrences of the item, click Change.

To make the change and continue searching for other occurrences, click Change & Find.

To change all occurrences of the item, specify all occurrences in the document or only occurrences in the current selection and click Change All.

Find and correct errors in document structure

An error in a structured flow can be a structure problem, such as an element in an invalid location, or an invalid attribute, such as an attribute with a missing required value. In Structure View, when a collapsed element has invalid content in its structure, the plus sign on the left of the element name is red.

You can also validate a document to find errors. After you know where the errors are located, use the Element Catalog and the Structure View as guides to help you correct them.

If you’ve made any formatting changes to text in elements, the elements perhaps do not conform to their format rules.

Use the Structure View to find errors

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.

At least one required child element is missing.

sa_23.png

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.

The Para element is invalid at this location.

sa_24.png

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.

The DraftVersion attribute is invalid.

sa_25.png

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.

The XRefLabel attribute is missing a required value.

sa_26.png
Validate a document

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.

Only the section’s child elements are validated.

sa_27.png

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.

1)Choose Element > Validate.

2)Select Entire Document, Entire Book, Current Flow, or Current Element to specify the scope of the validation.

3)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.

4)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.

5)If FrameMaker finds an error, click Start Validating again when you’re ready to continue vali­dating.

The top of the Element Validation dialog box shows the tag 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.

6)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 vali­dating. 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

1)Choose Element > Validate.

2)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

The following error messages can appear at the top of the Element Validation dialog box. (In the descriptions, tag represents an element tag, name represents an attribute name, and value represents an attribute value.)

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 tag

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 name 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 docu­ment (or in the book, if you’re validating a book).

The name attribute is undefined for this element

The definition of this element does not include a name 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 name attribute

The attribute value is the wrong type for the attribute.

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

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

Value for name attribute is not one of the allowed choices

The attribute’s value must match a value from the pop-up menu 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.

tag excluded in this element

The tag element is not allowed because of an exclusion rule for the parent or one of its ances­tors.

tag not permitted in this element

The tag element is not allowed anywhere in the parent element.

tag not valid at this position

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

Correct errors in elements

After you have identified errors in elements and attributes, use the Element 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, or if you’re validating, FrameMaker selects the element for you. When the element is selected, the Element Catalog shows which elements are valid at that location.

li or ListItem is valid at this location.

tx_list_item.png

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 Element Catalog shows which elements are valid at that location.

Title is required at this location.

tx_title_element.png

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 Special > Cross-Reference, and change to a source that has a valid ID.


September 30, 2016

Legal Notices | Online Privacy Policy