DITA Oriented Tips And Tricks

Add-ons

There are lots of free add-ons provided by the Oxygen team that can be installed in an Oxygen standalone version. I will enumerate some of the most interesting one:

Git add-on. This plugin adds a side view allowing you to do some common Git operations like pull, commit, push (mostly 90% of what a regular Git user would do).
Content Fusion Connector add-on. Collaborate with your peers by sending them links that allow them to give you feedback on your work using a web browser without the need to pre-install anything on their side.
Translation package builder. Small plugin that can be used to prepare a zip file containing only the topics that have changed from one version to another.
Batch convertor add-on. Converts multiple HTML, Markdown, Excel files to DITA.

Project-related Functionality:

The Oxygen Project view is the place where you can organize and apply batch changes to all your DITA resources:

Main files support. Enable main files support in the DITA project, add your top level DITA Maps as main files and any structure changes, renaming or moving files will automatically update all links in the DITA Project. Also works for renaming/moving image resources.
Store options at project level. Almost all of Oxygen's preferences pages can be saved at project level. Once you do that, you can share the project.xpr file with somebody else and when they open it, they will also get the settings set inside the project.
Compare files/folders.
Refer to multiple folders.
Batch operations: Select a folder in the project and use the "Transform", "Validate", "Format and Indent", "Find/Replace in Files", or "Spell Check in Files". Or use the "XML Refactoring" action to apply a refactoring stylesheet over all the selected files.
Filter files. You can instruct the Project view to hide various file types.

Navigation:

Actions to find opened files, find files containing a certain content or navigate between files.

In the main Window menu, you can find the Next/Previous Editor actions and their shortcuts. Together with the Switch editor tab action, these help you navigate between opened XML documents.
The Open/Find Resource view (main menu Window->Show View) allows you to search for file names, search in file contents, or search for files containing comments or change tracking.
Right-click the tab of an opened DITA document and use the Copy location action. Or use the Show in Explorer/Finder action to locate the file.
Use the main menu File->Reopen last closed editor action to re-open the last closed file.
Open a DITA topic in the Text editing mode, right click, choose Go to definition to open the DTD, XML Schema or RelaxNG Schema at the precise location where that DITA element is defined, something useful for debugging DITA specializations.
Use the Navigation toolbar to Go back/forward/last modification.

Find/Replace Functionality

The Find/Replace functionality is the bread and butter of any editing application and Oxygen has lots of functionality in this regard:

Find/Replace in Files.
- Restrict to XPath - If you want to make replacements only in certain parts of the XML document, the XPath restriction can be used to focus only on certain attributes or element content.
- Ignore Whitespaces - You should usually check this checkbox as there is always there is a possibility what the words you are searching for may be split on multiple lines in the XML content.
The Find menu → Find Next/Previous actions allow you to find the next/previous occurrence of the current selected word(s). Or you can use the Find All action to find and highlight all occurrences of a word or a sequence of words.
The Find menu → Find all Elements action shows a dialog box allowing you to find elements or attributes containing a sequence of words.
The Find menu → Quick find toolbar is a compact toolbar giving you access to search functionality.
The XPath allows you to use XPath expressions (i.e. //comment()[contains(., 'TODO')]) to search the current topic or a set of topics for elements, attributes, or comments matching a set of conditions.

DITA Maps Manager

The DITA Maps Manager view's contextual menu gives you quite an impressive array of useful actions:

Fast create new topics. Create a set of DITA topics by specifying only their titles.
Add references to multiple topics.
Create key definition with keyword.
Edit Properties - You can even set profiling attributes on multiple selected topic references.
Export DITA Map - Export your DITA Map to a zip archive ready for translation.
Find Unreferenced Resources - Find all resources which are no longer used in a DITA project.
Refactoring menu
- Rename/Move topic - Renames a topic and all references to it.
- Rename key - Rename a DITA key and all its references in the entire project.
- Conversions between topics - Convert between topics, tasks, concepts, and references for multiple selected DITA files.
- Convert nested sections to new topics - Convert all sections located inside a topic to new topics.
- Convert nested topics to new topic - Convert all nested topics to new topic files.
- Apply custom refactoring scripts - Create and apply your own XSLT or XQuery refactoring scripts.
Find/Replace in Files.
Spell Check in Files.
Search References - Search all references to a particular referenced topic.
Remove from Disk - Check in how many places a topic is referenced and then remove it from disk.
Open with resolved topics - Open the DITA Map with all topic references expanded, useful if you want to have an overview of the entire publication.
Synchronized selection between DITA Maps manager and main editor area - Anytime a DITA topic is opened both in the DITA Maps Manager and the main editing area, moving the selection in one instance will also move the selection to the corresponding place in the other.

Editing in the Author Visual Editing Mode

Maximize editor area - Double-click the opened editor's tab to hide all side views and maximize editing space, double click again to show the side views.
Increase/decrease editor font - Use Ctrl/CMD +/- to increase or decrease the font in the current edited document.
Inserting elements - Pressing ENTER in the Author visual editing mode will show you a list with all possible elements that can be inserted. If you choose an invalid element, Oxygen will find a place for it. You can also add custom actions or code templates to the content completion list.
Select content then press ENTER to surround the content in a new element.
Select multiple intervals - Press the Ctrl/CMD button when selecting text to select multiple text intervals. Once you do that, you can use toolbar actions like Bold, Italic, or Underline or you can use the Edit Profiling Attributes action to set profiling attributes on all the selected items.
In-place attributes editor - Instead of using the Attributes view, you can press Alt-Enter to edit attributes for the current element in a small pop-up dialog box.
Select an entire element - Triple-click inside an element's contents to select the entire element. After this, you can move the element to a new place.
Double-click to select by word, then drag the mouse to select the content word by word.
Move elements (especially paragraphs, list items) up or down (ALT-UP/DOWN), indent or unindent list items (Tab, Shift-Tab).
Select content and then use the Toggle comment action (contextual menu Refactoring submenu) to quickly add an XML comment around it.
In the contextual menu the Text submenu contains useful actions to count the number of words in the entire document (or in the selected text), convert the selection to upper, lowercase, or sentence case
Bookmarks - Click the vertical left side bar in the editing area to add a bookmark. Navigate to that bookmark even after the file has been closed using the Ctrl/CMD + number shortcut.
Collapse other folds - Click a fold triangle in the Author visual editing mode and you can choose to close all other folds, useful when working with multiple sections in the same file.
Code templates - Define small fragments of XML content that can be inserted either by defining a shortcut key or by pressing ENTER in the editing area.
Editor variables - Certain Oxygen-specific macros can be automatically expanded. For example, a code template that inserts the current author name can use this editor variable:
```
<author>${author.name}</author>
```
or a code template that surrounds the selection inside a <keyword> element:
```
<keyword>${selection}</keyword>
```
or a code template that first asks the end user for their name and then inserts it in the document:
```
<author>${ask('Author Name', generic, 'John Doe')}</author>
```
Code templates can also be used when creating new file templates.
Outline Quick find filter - The Outline view contains a filter that can be used to reduce the number of elements displayed in it (for example, display only the contained topics).

DITA-specific Editing in the Author Visual Editing Mode

DITA Reusable Components view. You can use this side view to quickly search for and insert references to keys or to reusable components.
Inserting links to resources. Besides using the toolbar actions you can also:
- Drop a file from an outside location. Drag a DITA topic or other resource from the Explorer/Finder or from the Oxygen Project and drop it inside an opened DITA topic to insert a reference to it.
- Paste a URL in the editing area to insert a reference to it.
Links to images:
- Drop images from the Project view in the main editing area to insert references to them.
- Copy an image and then paste it in the editing area to insert a reference to it.
- Double-click broken image reference to modify attributes.
Reuse content:
- Copy an element that has an ID set on it and then right-click elsewhere and use the "Paste Special → Paste as content reference" to insert a content reference to the element.
Select multiple sibling paragraphs and use the Insert list item toolbar item to convert them all to list items. Select multiple list items and use the Insert table toolbar action to convert them to a table.
Working with tables:
- You can right-click inside a table and use the Table Properties action to change lots of table-related settings.
- You can sort tables based on certain criteria.
- In the contextual menu Refactoring submenu you can find actions to convert between CALS and simple tables.
- You can select an entire table by clicking its left corner and select an entire row by clicking to the left of it.
Add hotspots to images - You can right-click any image reference and use the Image Map Editor to configure target links for various parts of the image.
You can right-click inside an element and use the About Element contextual menu item to find out more about it.
Pasting content from web browsers, Excel spreadsheets, or Word documents inside a DITA topic produces the equivalent DITA content.
The Styles drop-down toolbar menu allows you to choose between various CSS styles to apply while editing. The Hints and Inline actions layers should be interesting for you to experiment with. Or you can add your own.

Preferences:

Oxygen has a lot of global settings that can be configured, I will just list what I consider to be the most important ones:

Menu shortcut keys - You can use this preferences page to assign or to see the shortcut for any action available in Oxygen.

Fonts - This page allows you to change the default fonts used in the application.

Appearance - Change the default color theme in Oxygen (the Graphyte theme is quite popular).

Spell check - Customize the spell checker settings, use custom spell check dictionaries.

Save - Settings to automatically save or to check for errors before saving the file.

External tools - Define various command line tools that you can launch from Oxygen.

Annotations - Disable the tooltips which appear when hovering over various elements (useful if you have a small screen).

Tools

The Tools main menu is worth exploring sometimes. You can invoke XML refactoring actions from it or open other small applications like the SVG viewer.

Import

The File menu offers the possibility to import HTML, CSV, Excel files, or database content as XML.

Other Views and Toolbars:

You can right-click in the toolbar area and use the Configure Toolbars action to see what toolbars are available or what toolbars can be removed.

The Symbols toolbar is quite interesting if you often want to insert symbols that are not on the current keyboard.

Other Small Tips:

The main Window menu has actions to tile all opened XML documents and also to enable synchronous scrolling in them (useful if you want to look at similar XML documents and maybe to copy/paste between them).

Keeping in Touch

Oxygen's Help menu allows you to use the Report problem action to contact us directly. The Support Tools->Randomize XML Content action allows you to randomize the content of an XML project before sending it to us for tests.

And there are a lot of other ways to get in touch with us or to find various videos or tutorials to read: https://www.oxygenxml.com/technical_support.html.