Editing DITA Maps

DITA Maps organize topics for output to a specific deliverable, including generating navigation files and links to related topics. <oXygen/> provides a special DITA Maps editing view.

The DITA Maps Manager view presents maps in a simplified table-of-contents manner allowing the user to easily navigate the referred topics, make changes and perform transformations to various output formats using the DITA-OT framework bundled with <oXygen/>.

 

Figure 4.52. The DITA Maps Manager view

The DITA Maps Manager view

The Maps Manager view supports opening multiple documents at the same time.

All files which have the extension .ditamap and are opened in the application will be opened in the DITA Maps Manager view. In additional you can right click the file in the Project view and select Open with. After the map is opened in the Manager you can open it in the main editor for further customization using the Open map in editor toolbar action.

[Note]Note

A map opened from WebDAV can be locked when it is opened in DITA Maps Manager by checking the option Lock WebDAV files on open to protect it from concurrent modifications on the server by other users. If other user tries to edit the same map he will receive an error message and the name of the lock owner. The lock is released automatically when the map is closed from <oXygen/> DITA Maps Manager.

In additional to being available on the toolbar and on the contextual menu, more navigation actions and all edit actions appear in the DITA Maps menu. The menu is only available when the view is active on screen.

 

Figure 4.53. DITA Maps menu

DITA Maps menu


The following general actions can be performed on an opened DITA Map :

Open

Allows opening the DITA Map in the DITA Maps Manager view.

Open URL

Allows opening remote DITA Maps in the DITA Maps Manager view. See Open URL for details.

Save

Allows saving the currently opened DITA Map.

Apply Transformation Scenario

Allows the user to start the DITA ANT Transformation scenario associated with the opened map. For more transformation details see here.

Configure Transformation Scenario

Allows the user to configure a DITA ANT Transformation scenario for the opened map. For more transformation details see here.

Refresh References

Sometimes after a topic was edited and its title changed the topic's title needs to be also updated in the DITA Maps manager view. You can use this action to refresh and update titles for all referred topics.

Open map in editor

For complex operations which cannot be performed in the simplified DITA Maps view (like editing a relationship table) you can open the map in the main editing area. See more about editing a map in the main edit area here.

[Tip]Tip

The additional edit toolbar can be shown by clicking the "Show/Hide additional toolbar" expand button located on the general toolbar.

The following edit actions can be performed on an opened DITA Map:

Insert Topic Reference

Inserts a reference to a topic file. See more about this action here.

Insert Topic Heading

Inserts a topic heading. See more about this action here

Insert Topic Group

Inserts a topic group. See more about this action here.

Edit properties

Edit the properties of a selected node. See more about this action here.

Edit attributes

Edits the attributes of a selected node. A dialog is presented allowing the user to see and edit the attributes of the selected node. See here for more details about editing attributes.

Delete

Deletes the selected nodes.

Move Up

Moves the selected nodes in front of their respective previous siblings.

Move Down

Moves the selected nodes after their next respective siblings.

Promote

Moves the selected nodes after their respective parents as a siblings.

Demote

Moves the selected nodes as children to their respective previous siblings.

The contextual menu contains, in addition to the edit actions described above, the following actions:

Open in editor

Open in the editor the resources referred by the selected nodes

Cut, Copy, Paste, Undo, Redo

Common edit actions with the same functionality as those found in the text editor

Paste before, Paste after

Will paste the content of the clipboard before respectively after the selected node.

Append Child/Insert After
Topic reference

Append/Insert a topic reference as a child/sibling of the selected node

Topic reference to the current edited file

Append/Insert a topic reference to the current edited file as a child/sibling of the selected node

Topic heading

Append/Insert a topic heading as a child/sibling of the selected node

Topic group

Append/Insert a topic group as a child/sibling of the selected node

You can also arrange the nodes by dragging and dropping one or more nodes at a time. Drop operations can be performed before, after or as child of the targeted node. The relative location of the drop is indicated while hovering the mouse over a node before releasing the mouse button for the drop.

Drag and drop operations allow you to:

Copy

Select the nodes you want to copy and start dragging them. Before dropping them in the appropriate place, press and hold the CTRL key(META key on Mac). The mouse pointer should change to indicate that a copy operation will be performed.

Move

Select the nodes you want to move and drag and drop them in the appropriate place.

Promote / Demote

You can move nodes between child and parent nodes which ensures both Promote and Demote operations.

[Tip]Tip

You can open and edit linked topics easily by double clicking the references or by right-clicking and choosing "Open in editor". If the referenced file does not exist you will be allowed to create it.

By right clicking the map root element you can open and edit it in the main editor area for more complex operations.

You can decide to open the reference directly in the Author page and keep this setting as a default.

[Note]Note

Some of the common actions from the main application menu/toolbar also apply to the DITA Maps Manager when it has focus. These actions are:

File actions

Save, Save As, Save to URL, Save All, Print, Print preview, Close, Close others, Close all

Edit actions

Undo, Redo, Cut, Copy, Paste, Delete

The Save all action applies to all editors opened in either <oXygen/> work area or the DITA Maps Manager.

 Advanced operations

 Inserting a Topic Reference

The topicref element identifies a topic (such as a concept, task, or reference) or other resource. A topicref can contain other topicref elements, allowing you to express navigation or table-of-contents hierarchies, as well as implying relationships between the containing topicref and its children. You can set the collection-type of a container topicref to determine how its children are related to each other. You can also express relationships among topicref's using group and table structures (using topicgroup and reltable). Relationships end up expressed as links in the output (with each participant in a relationship having links to the other participants by default).

A reference to a topic file may be inserted both from the toolbar action and the contextual node actions. The same dialog can be used to insert references to maps or links to non-dita files like pdf's.

 

Figure 4.54. Insert Topic Reference Dialog

Insert Topic Reference Dialog

By using the Insert Topic Reference Dialog you can easily browse for and select the source topic file. The Target combo box shows all available topics that can be targeted in the file. Selecting a target modifies the Href value to point to it. The Format and Scope combos are automatically filled based on the selected file. You can specify and enforce a custom navigation title by checking the Navigation title checkbox and entering the desired title.

The file chooser located in the dialog allows you to easily select the desired topic. The selected topic file will be added as a child/sibling of the current selected topic reference. You can easily insert multiple topic references by keeping the dialog opened and changing the selection in the DITA Maps Manager tree.

 Inserting a Topic Heading

The topichead element provides a title-only entry in a navigation map, as an alternative to the fully-linked title provided by the topicref element.

A topic heading can be inserted both from the toolbar action and the contextual node actions.

 

Figure 4.55. Insert Topic Heading Dialog

Insert Topic Heading Dialog

By using the Insert Topic Heading Dialog you can easily insert a topichead element. The Navigation title is required but other attributes can be specified as well from the dialog.

 Inserting a Topic Group

The topicgroup element identifies a group of topics (such as a concepts, tasks, or references) or other resources. A topicgroup can contain other topicgroup elements, allowing you to express navigation or table-of-contents hierarchies, as well as implying relationships between the containing topicgroup and its children. You can set the collection-type of a container topicgroup to determine how its children are related to each other. Relationships end up expressed as links in the output (with each participant in a relationship having links to the other participants by default).

A topic group may be inserted both from the toolbar action and the contextual node actions.

 

Figure 4.56. Insert Topic Group Dialog

Insert Topic Group Dialog

By using the Insert Topic Group Dialog you can easily insert a topicgroup element. The Type, Format, Scope and Collection type attributes can be specified from the dialog.

 Edit properties

The Edit properties action, available both on the toolbar and on the contextual menu, is used to edit the properties of the selected node. Depending on the selected node, the action will perform the following tasks:

  • If a topicref element is selected, the action will show a dialog similar with the Insert Topic Reference dialog allowing the editing of some important attributes.

  • If a topichead element is selected, the action will show a dialog similar with the Insert Topic Heading dialog allowing the editing of some important attributes.

  • If a topicgroup element is selected, the action will show a dialog similar with the Insert Topic Group dialog allowing the editing of some important attributes.

  • If the map's root element is selected then the user will be able to easily edit the map's title using the Edit Map title dialog:

 

Figure 4.57. Edit Map Title Dialog

Edit Map Title Dialog

By using this dialog you can also specify whether the title will be specified as the title attribute to the map or as a title element (for DITA-OT 1.1) or specified in both locations.