Edit online

DITA Maps Preferences

To access the DITA Maps preferences page, open the Preferences dialog box (Options > Preferences) and go to DITA > Maps. This preferences page includes the following options:

DITA Maps file patterns
Allows you to specify the extension types that will be handled as DITA maps when opened in Oxygen XML Editor.
When opening a map
Oxygen XML Editor can open a DITA map in the regular editor view or in the DITA Maps Manager. This option allows you to specify how a map will be opened. You can choose one of the following options:
  • Always open in the DITA Maps Manager - A DITA map file is always opened in the DITA Maps Manager view.
  • Always open as XML - A DITA map file is always opened in the XML editor.
  • Always ask - When opening a DITA map, you are prompted to choose between opening it in the XML editor panel or in the DITA Maps Manager view.
Expand references to other maps when opening a map in Author mode
Enabling this option will improve performance (decrease the loading time) when opening maps in Author mode (particularly maps that contain a large amount of submaps). This option is disabled by default.
Note: You must close and reopen the map to see the effects of enabling/disabling this option.

DITA Maps Manager section

Automatically save local DITA maps after each modification
If selected (default), local DITA maps that are edited in the DITA Maps Manager are automatically saved whenever a modification is made.
Warning: This option is ignored if the Validate document before saving option in the Editor > Save preferences page is also selected.
Only display items related to currently open maps in the Context drop-down list
If selected, only the currently open maps and contexts that are relevant to the currently open maps are displayed in the Context map drop-down menu in the DITA Maps Manager. This is helpful if you are working with multiple DITA-OT projects and DITA maps set as Main Files since it helps you narrow down the relevant contexts.
Prefer using the navigation title for rendering topic references
If selected and there is a @navtitle attribute set on a <topicref>, then the @navtitle is used to render the title of the topic in the DITA Maps Manager.
Allow referenced submaps to be edited
If selected, all DITA maps referenced directly or indirectly in a DITA map that is open in the DITA Maps Manager view will be fully editable. You will be able to add new topic references, modify properties, and move topic references from one submap to another. Saving the main DITA map will also save the contents of the modified submaps.
Attention: The documents must be reopened to apply a change to this option.
Local files only
If selected, only submaps that are located on local disk drives will be editable. As for maps located in remote locations (e.g. content management systems), the save operation might not work on all submaps. This checkbox is selected by default.

Inserting Topic References section

Always set values for the following attributes
Allows you to specify that when inserting a topic reference (using the Insert Reference dialog box and Edit Properties dialog box), the values for certain attributes will always be automatically populated with a detected value (based on the specifications), even if it is the same as the default value. You can choose to always populate the values for the following attributes:
  • Format - If selected, the @format attribute will always be automatically populated with a detected value.
  • Scope - If selected, the @scope attribute will always be automatically populated with a detected value.
  • Type - If selected, the @type attribute will always be automatically populated with a detected value.
  • Navigation title - If selected, the @navtitle attribute will always be automatically populated with a detected value.
Use the file name as the value of the "keys" attribute
If selected, when inserting a topic reference into a map, the file name will be used as the value of the @keys attribute for the new <topicref>. The key is not defined on the <topicref> for references to DITA maps. This option has a slightly different effect depending on the method used for inserting the topic reference:
  • Drag/Drop or Copy/Paste in the DITA Maps Manager - If you drag or copy a resource from another view (or outside Oxygen XML Editor) and drop or paste it into the DITA Maps Manager and a key is already defined for that resource, a @keyref attribute will be inserted instead. This even works for two consecutive drag/drop or copy/paste operations without saving the file and it works for multiple selections of topic references.
  • Drag/Drop or Copy/Paste in a Map opened in Author Mode - If you drag or copy a resource from another view (or outside Oxygen XML Editor) and drop or paste it into a map that is open in Author mode and a key is already defined for that resource, a @keyref attribute will be inserted instead.
    Restriction: In this particular scenario, if you perform two identical, consecutive drag/drop or copy/paste operations without saving the file between operations, the value of the @keys attribute will be the same for both inserted topic references. The workaround for this limitation is to simply save the map after each drag/drop or copy/paste operation.
  • Using the Fast Create Topics or Duplicate Actions - If you use the Fast Create Topics feature or Duplicate action to insert topic references, the newly created <topicref> elements will contain the @keys attribute with its value set depending on the file name.
  • Using the Insert Topic Reference Dialog Box from the DITA Maps Manager - If you use an action in the DITA Maps Manager to insert topic references (e.g. Append Child > Reference), a @keys attribute will be set for each inserted topic reference and the value depends on the file name. If a single target was selected, you can see the value in the Define keys field from the Keys tab of the Insert Reference dialog box and you can change it, while if multiple targets were selected, the values are automatically generated based on each file name when the insertion is performed, and you cannot see or change the values in that dialog box.
Note: This option also has an effect on image references. When inserting a reference to an image in a DITA map and this option is selected, a <keydef> element is created if it is allowed by the schema. If it is not allowed (or this option is deselected), a specific topic reference element is created with the value of the @processing-role attribute set to resource-only.
Prefer adding key references to already referenced resources
If selected, when a topic reference is inserted into a map and a key is already defined for that resource, a @keyref attribute is inserted for the new <topicref>. If not selected, an @href attribute is inserted instead.
Dynamic conversion of specific non-DITA resources
If selected (default), non-DITA documents are dynamically converted to DITA when they are chosen in the Insert Reference dialog box and the IDs from the resulting DITA content are presented in the dialog box. If not selected, non-DITA documents (Word, Excel, Markdown, OpenAPI, and HTML) are not dynamically converted when they are chosen in the dialog box.

Review section

When the last/first item is reached while navigating review items
This option allows you to specify what should happen when you are navigating review items in the Review view and you reach the last or first review item. You can choose one of the following options:
  • Open the next/previous document (in the current DITA map hierarchy) that contains review items - If you reach the last/first review item in the document, clicking the Next or Previous navigation buttons will open the next/previous document (from the current DITA map hierarchy) that contains review items.
  • Do nothing - If you reach the last/first review item in the document, clicking the Next or Previous navigation buttons will do nothing.
  • Always ask - If you reach the last/first review item in the document, clicking the Next or Previous navigation buttons will open a dialog box asking if you want to open the next/previous document (from the current DITA map hierarchy) that contains review items.