Edit online

Built-in Refactoring Operations

The XML Refactoring tool includes a variety of built-in operations that can be used for common refactoring tasks. They are grouped by category in the Refactoring operations wizard page. You can also access the operations from the Refactoring submenu in the contextual menu of Author or Text mode. The operations are also grouped by category in this submenu. When selecting the operations from the contextual menu, Oxygen XML Author considers the editing context to get the names and namespaces of the current element or attribute, and uses this information to preconfigure some of the parameter values for the selected refactoring operation.

Tip: Each operation includes a link in the lower part of the wizard that opens the XML / XSLT-XQuery / XPath preferences page where you can configure XPath options and declare namespace prefixes.

The following built-in operations are available:

Refactoring Operations for Attributes

Add/Change attribute

Use this operation to change the value of an attribute or insert a new one. This operation allows you to specify the following parameters:

Parent element section

Element: The parent element of the attribute to be changed, in the form of a local name from any namespace, a local name with a namespace prefix, or an XPath expression.

Attribute section

Local name: The local name of the affected attribute.
Namespace: The namespace of the affected attribute.
Value: The value for the affected attribute.

Options section

You can choose between one of the following options for the Operation mode:

Add the attribute in the parent elements where it is missing: Adds the attribute to all instances of the specified parent element.
Change the value in the parent elements where the attribute already exists: Replaces the value of the already existing attribute in all instance of the specified parent element.
Both: Adds the attributes to the instances where it is missing and replaces the value in instances where the attribute already exists.

Convert attribute to element

Use this operation to convert a specified attribute to an element. This operation allows you to specify the following parameters:

Parent element section

Element: The parent element of the attribute to be converted, in the form of a local name from any namespace, a local name with a namespace prefix, or an XPath expression.

Attribute section

Local name: The local name of the affected attribute.
Namespace: The namespace of the affected attribute.

New element section

Local name: The local name of the new element.
Namespace: The namespace of the new element.

Delete attribute

Use this operation to remove one or more attributes. This operation requires you to specify the following parameters:

Element: The parent element of the attribute to be deleted, in the form of a local name from any namespace, a local name with a namespace prefix, or an XPath expression.
Attribute: The name of the attribute to be deleted.

Rename attribute

Use this operation to rename an attribute. This operation requires you to specify the following parameters:

Element: The parent element of the attribute to be renamed, in the form of a local name from any namespace, a local name with a namespace prefix, or an XPath expression.
Attribute: The name of the attribute to be renamed.
New local name: The new local name of the attribute.

Replace in attribute value

Use this operation to search for a text fragment inside an attribute value and change the fragment to a new value. This operation allows you to specify the following parameters:

Target attribute section

Element: The parent element of the attribute to be modified, in the form of a local name from any namespace, a local name with a namespace prefix, or an XPath expression.
Attribute: The name of the attribute to be modified.

Find / Replace section

Find: The text fragments to find. You can use Perl-like regular expressions.
Replace with: The text fragment to replace the target with. This parameter can bind regular expression capturing groups ($1, $2, etc.) from the find pattern.

Refactoring Operations for Comments

Delete comments

Use this operation to delete comments from one or more elements. This operation requires you specify the following parameter:

Element: The target element (or elements) that will have comments deleted, in the form of a local name from any namespace, a local name with a namespace prefix, or an XPath expression.

Note: Comments that are outside the root element will not be deleted because the serializer preserves the content before and after the root.

Refactoring Operations for DITA Topics

Change topic ID to file name

Use this operation to change the ID of a topic to be the same as its file name.

Convert CALS tables to simple tables

Use this operation to convert DITA CALS tables to simple tables.

Convert DITA 1.3 Maps and Topics to DITA 2.0

Use this operation to convert topics and maps that adhere to the DITA 1.3 standard to the DITA 2.0 standard.

Changes DOCTYPE declarations and XML Schema/Relax NG schema references.
DITA Map changes:
- Removes the @lockmeta attribute.
- Removes the <topicset> and <topicsetref> elements.
- Removes the <anchor> and <anchorref> elements and the @anchorref attribute.
- Migrates the @navtitle attribute as a <navtitle> element.
- Migrates the @title attribute as a <title> element.
- Converts the @copy-to attribute to a <resourceid> element.
- Replaces the @print attribute with an @deliveryTarget attribute.
- Convert topicmeta <linktext> to <linktitle>.
- Removed <hasInstance>, <hasKind>, <hasNarrower>, <hasPart>, <hasRelated>, and <relatedSubjects> from subject scheme relationship tables in subject scheme, including <subjectRelTable>, <subjectRelHeader>, <subjectRel>, and <subjectRole>.
DITA task changes:
- Converts the <substep> element to a <step> element.
- Converts the <substeps> element to a <steps> element.
DITA topic changes:
- Removes the @type attribute with the value fastpath.
- Converts the @alt attribute to an <alt> element.
- Replaces the <index-sort-as> element with a <sort-as> element.
- Removes the <itemgroup> element.
- Moves the contents of the <titlealts> element inside the <prolog>.
- Removes the @domains attribute.
- Renames <sectiondiv> to <div>.
- Remove @query attribute from <link> element.
- Remove @specentry attribute from <stentry> element.
  
  Remove the @spectitle attribute.

Convert conrefs to conkeyrefs

Use this operation to convert @conref attributes to @conkeyref attributes. For more information and instructions for using this operation, see Converting Conrefs to Conkeyrefs.

Convert Nested Topics to New Topics (Available from the contextual menu of editable maps/nodes in the DITA Maps Manager)

Use this operation on topics that contain nested <topic> elements to convert each nested topic to a new topic. Also, the new topics are added in the DITA Maps Manager as the first child topics of the original topic.

Convert Sections to New Topics (Available from the contextual menu of editable maps/nodes in the DITA Maps Manager)

Use this operation on topics that contain multiple sections to convert each section to a new topic. Also, the new topics are added in the DITA Maps Manager as the first child topics of the original topic.

Convert simple tables to CALS tables

Use this operation to convert DITA simple tables to CALS tables.

Convert to Concept

Use this operation to convert a DITA topic (of any type) to a DITA Concept topic type (for example, Topic to Concept). For more information, see Converting DITA Topics to Another Type.

Convert to General Task

Use this operation to convert a DITA topic (of any type) to a DITA General Task topic type (for example, Task to General Task). For more information, see Converting DITA Topics to Another Type.

Convert to Reference

Use this operation to convert a DITA topic (of any type) to a DITA Reference topic type (for example, Topic to Reference). For more information, see Converting DITA Topics to Another Type.

Convert to Task

Use this operation to convert a DITA topic (of any type) to a DITA Task topic type (for example, Topic to Task). For more information, see Converting DITA Topics to Another Type.

Convert to Topic

Use this operation to convert a DITA topic (of any type) to a DITA Topic (for example, Task to Topic). For more information, see Converting DITA Topics to Another Type.

Convert to Troubleshooting

Use this operation to convert a DITA topic (of any type) to a DITA Troubleshooting topic type (for example, Topic to Troubleshooting). For more information, see Converting DITA Topics to Another Type.

Rename Key

Use this operation to rename a key. It also updates all references to it.

Note: It does not work on DITA 1.3 key scopes.

Generate IDs

Use this operation to automatically generate unique IDs for elements.

Scope and Filters:

All of the DITA refactoring actions allow you to choose a scope for the operation and some filters:

Scope

Select from a variety of options to define the scope that will have resources affected by the operation. For example, you can choose to affect all resources in the Project, All opened files, Current DITA map hierarchy, or just the Current file.

Filters section

Include files: Specifies files to be excluded from the operation. You can specify multiple files by separating them with commas and the patterns can include wildcards (such as * or ?).
Restrict to known XML file types only: Excludes non-XML file types from the operation.
Look inside archives: If this option is selected, the scope of the operation will include files inside archives.

Refactoring Operations for DITA Maps

Convert DITA Bookmap to Map: Convert a DITA bookmap to a DITA map.
Convert DITA Map to Bookmap: Convert a DITA map to a DITA bookmap.
Change or remove profiling attribute value: Change or remove a value from a DITA profiling attribute. A profiling attribute can have multiple values, separated by spaces (e.g. for platform="windows redhat", you can change the current redhat value to linux). Select the name of the profiling attribute, the current value to replace, and the new value. If the new value is left empty, the current value is removed from the profiling attribute. The new value is modified and reflected in DITA maps, DITA topics, and DITAVAL files.
Define keys for all topic references: This refactoring action is useful for converting links inside a DITA project from direct to indirect key-based addressing. When applied on DITA resources from your project (DITA maps and topics), this refactoring action defines keys for all of a DITA map's topic references based on the referenced file name and converts each direct reference to a key reference in each DITA topic. If a topic references already has keys defined, the action does not define new ones. Inside the DITA topics, whenever there is a link element (<xref> or <link>) with a direct reference to another DITA topic or an element with a @conref, the action attempts to convert them to indirect key-based addressing. The refactoring action may introduce linking errors or create duplicate keys so it is advised to run the Validate and check for completeness action from the DITA Maps Manager toolbar to manually fix those problems. You can enable the Report duplicate keys checkbox to also report any keys that are defined more than once.

Scope and Filters:

All of the DITA refactoring actions allow you to choose a scope for the operation and some filters:

Scope

Filters section

Include files: Specifies files to be excluded from the operation. You can specify multiple files by separating them with commas and the patterns can include wildcards (such as * or ?).
Restrict to known XML file types only: Excludes non-XML file types from the operation.
Look inside archives: If this option is selected, the scope of the operation will include files inside archives.

Refactoring Operations for Elements

Delete element

Use this operation to delete elements. This operation requires you to specify the following parameter:

Element: The target element to be deleted, in the form of a local name from any namespace, a local name with a namespace prefix, or an XPath expression.

Delete element content

Use this operation to delete the content of elements. This operation requires you to specify the following parameter:

Element: The target element whose content is to be deleted, in the form of a local name from any namespace, a local name with a namespace prefix, or an XPath expression.

Insert element

Use this operation to insert new elements. This operation allows you to specify the following parameters:

Element section

Local name: The local name of the element to be inserted.
Namespace: The namespace of the element to be inserted.

Location section

XPath: An XPath expression that identifies an existing element to which the new element is relative, in the form of a local name from any namespace, a local name with a namespace prefix, or other XPath expressions.
Position: The position where the new element will be inserted, in relation to the specified existing element. The possible selections in the drop-down menu are: After, Before, First child, or Last child.

Rename element

Use this operation to rename elements. This operation requires you to specify the following parameters:

Target elements (XPath): The target elements to be renamed, in the form of a local name from any namespace, a local name with a namespace prefix, or other XPath expressions.
New local name: The new local name of the element.

Unwrap element

Use this operation to remove the surrounding tags of elements, while keeping the content unchanged. This operation requires you to specify the following parameter:

Target elements (XPath): The target elements whose surrounding tags will be removed, in the form of a local name from any namespace, a local name with a namespace prefix, or other XPath expressions.

Wrap element

Use this operation to surround elements with element tags. This operation allows you to specify the following parameters:

Target elements (XPath)

The target elements to be surrounded with tags, in the form of a local name from any namespace, a local name with a namespace prefix, or other XPath expressions.

Wrapper element section

Local name: The local name of the Wrapper element.
Namespace: The namespace of the Wrapper element.

Wrap element content

Use this operation to surround the content of elements with element tags. This operation allows you to specify the following parameters:

Target elements (XPath)

The target elements whose content will be surrounded with tags, in the form of a local name from any namespace, a local name with a namespace prefix, or other XPath expressions.

Wrapper element section

Local name: The local name of the Wrapper element that will surround the content of the target.
Namespace: The namespace of the Wrapper element that will surround the content of the target.

Refactoring Operations for Fragments

Insert XML fragment

Use this operation to insert an XML fragment. This operation allows you to specify the following:

XML Fragment

The XML fragment to be inserted.

Location section

XPath: An XPath expression that identifies an existing element to which the inserted fragment is relative, in the form of a local name from any namespace, a local name with a namespace prefix, or other XPath expressions.
Position: The position where the fragment will be inserted, in relation to the specified existing element. The possible selections in the drop-down menu are: After, Before, First child, or Last child.

Replace element content with XML fragment

Use this operation to replace the content of elements with an XML fragment. This operation allows you to specify the following parameters:

Target elements (XPath): The target elements whose content will be replaced, in the form of a local name from any namespace, a local name with a namespace prefix, or other XPath expressions.
XML Fragment: The XML fragment with which to replace the content of the target element.

Replace element with XML fragment

Use this operation to replace elements with an XML fragment. This operation allows you to specify the following parameters:

Target elements (XPath): The target elements to be replaced, in the form of a local name from any namespace, a local name with a namespace prefix, or other XPath expressions.
XML Fragment: The XML fragment with which to replace the target element.

Refactoring Operations for JATSKit

Add BITS DOCTYPE - NLM/NCBI Book Interchange 2.0: Use this operation to add an NLM 'BITS' 2.0 DOCTYPE declaration.
Add Blue DOCTYPE - NISO JATS Publishing 1.1: Use this operation to add a JATS 'Blue' 1.1 DOCTYPE declaration.
Normalize IDs: Use this operation to normalize assigned IDs and assigned IDs to elements that are missing them.

All of these JATSKit refactoring actions allow you to choose a scope for the operation and some filters:

Scope

Select from a variety of options to define the scope for the resources that will be affected by the operation. For example, you can choose to affect all resources in the Project, All opened files, or just the Current file.

Filters section

Include files: Specifies files to be excluded from the operation. You can specify multiple files by separating them with commas and the patterns can include wildcards (such as * or ?).
Restrict to known XML file types only: Excludes non-XML file types from the operation.
Look inside archives: If this option is selected, the scope of the operation will include files inside archives.

Refactoring Operations for Processing Instructions

Accept all tracked changes, remove all Oxygen-specific comments and highlights

Use this operation to accept all application-specific tracked changes (from elements and attributes) or remove all application-specific comments or highlights. There are several options to choose from:

Accept all tracked changes: Accepts all application-specific tracked changes (from elements and attributes).
Remove comments: Removes all application-specific comments.
Remove highlights: Removes all application-specific highlights.

Delete processing instructions

Use this operation to delete all processing instructions that have a certain target name from the processed documents. This operation requires you to specify the following parameter:

Processing instruction target: The target name of the processing instructions to delete.

Note: Processing instructions that are outside the root element are not deleted because the serializer preserves the content before and after the root.

Refactoring Operations for Publishing Template

These operations are for those who use Oxygen Publishing Templates for WebHelp Responsive output customization.

Migrate HTML Page Layout Files to v21: Use this operation to convert custom HTML page layout files that are included in a custom Publishing Template that was created in Oxygen XML Author version 20.0 or 20.1 so that they will be compatible with Oxygen XML Author version 21.0.
Migrate HTML Page Layout Files to v22: Use this operation to convert custom HTML page layout files that are included in a custom Publishing Template that was created in Oxygen XML Author versions 20.0 - 21.1 so that they will be compatible with Oxygen XML Author version 22.0.
Update HTML Pages: Attention: This operation is only used by Oxygen XML Author and should not be used manually.

Additional Notes:

There are some operations that allow <ANY> for the local name and namespace parameters. This value can be used to select an element or attribute regardless of its local name or namespace. Also, the <NO_NAMESPACE> value can be used to select nodes that do not belong to a namespace.
Some operations have parameters that accept XPath expressions to match elements or attributes. In these XPath expressions you can only use the prefixes declared in the Options > Preferences > XML > XSLT-XQUERY > XPath page. This preferences page can be easily opened by clicking the link in the note (Each prefix used in an XPath expression must be declared in the Default prefix-namespace mappings section) at the bottom of the Configure Operation Parameters wizard page.