Editor Overview

Topic Editor

Use the topic editor to simultaneously collaborate on DITA topics and maps.

Overview

Figure 1. Topic Editor.

The following example shows a map opened in the topic editor.

Toolbar

The toolbar enables you to perform common typographic and DITA-related actions.

Figure 2. Topic Editor Toolbar

Context Menu

The context menu appears when you right-click the content in the topic editor.

Quick Insert Menu

The quick insert menu enables you to quickly insert a DITA element in a valid position. You can open the menu by pressing Ctrl > Enter (Windows) or Cmd > Enter (Mac) or clicking the plus icon.

Figure 3. Quick Insert Menu
Tip: The elements that display in the quick insert menu are context-sensitive and the arrows indicate if the element will be a parent, sibling, or child of the element in which you have your cursor. To change the element suggestion mode, use the Insert drop-down menu and select Before , After or Intelligently .

Keyboard Shortcuts

easyDITA enables you to quickly perform common actions by using keyboard shortcuts. You can access the keyboard shortcut list by clicking the keyboard icon in the toolbar.

Footer

When you hover over an element in the structure bar at the bottom of the topic editor, easyDITA highlights that element and a flying arrow pointing to the element. If you click an element in the structure bar, easyDITA gives you options for interacting with that element, such as removing it, moving it up or down in the topic, or inserting a list.

Figure 4. Footer

Editing Modes

Use the topic editor in one of four different modes, each of which offers increased ability to interact with a topic.

Viewing

Viewing mode is read-only. In viewing mode, you can only see a topic's content but cannot leave comments or make changes to the content.

Commenting

Commenting mode enables you to leave comments on the content in a topic, but you cannot change any of the source content.

Suggesting

Suggesting mode enables you to leave inline, tracked changes, which can be accepted or rejected. easyDITA underlines suggested additions and strikes through suggested deletions. Each user's suggestions appear in a different color.

Editing

Editing mode provides full editing privileges. Editing mode provides users the ability to add elements, attributes, and content. Any content added or changes you make while in editing mode are immediately part of the source content.

Tags

Use different tags modes to see and interact with the elements that are present in your content.

Tag Modes

In the topic editor, you can switch between different tag modes by clicking the gear icon and using the Tags drop-down menu.

Figure 5. Tags Menu
The Full Tags With Attributes, Full Tags, and Short Tags modes enable you to:
  • Select elements by clicking tags
  • Drag and drop tags
  • Drag and drop tags between different topic editors

    In the following example, the ul tag is being dragged and dropped from one browser window to another browser window.

    Tip: If you drag-and-drop an element with an ID attribute assigned (for example from a warehouse topic), you can decide if you want to paste the element or create a content reference (conref).
  • Replace an element with another element by using the Tag context menu
  • Unwrap an element by using the Tag context menu

Tags Off

In the Tags Off mode, the topic editor does not show tags for DITA elements.

Figure 6. Tags Off

Short Tags

In the Short Tags mode, the topic editor shows generic indicators for the presence of DITA elements.

Figure 7. Short Tags

Full Tags

In the Full Tags mode, the topic editor shows descriptive tags for DITA elements.

Figure 8. Full Tags

Full Tags With Attributes

In the Full Tags With Attributes mode, the topic editor shows descriptive tags for DITA elements along with the attributes assigned to these elements.

Figure 9. Full Tags With Attributes

Text Placeholders

Disabling text placeholders makes the editing area less busy.

In the topic editor, you can show or hide text placeholders for common elements by clicking the gear icon and selecting Text Placeholders.

Figure 10. Enabled Text Placeholders
Figure 11. Disabled Text Placeholders

Topic Toolbars

Hiding topic toolbars, provides a streamlined document view.

Toggle

In the topic editor, you can show or hide topic toolbars by clicking the gear icon and selecting Topic Toolbars.

Status Selector

The status selector enables you to manually change the status of a topic. For example, you can change a status from In Progress to Approved status.

Open In New Window Icon

If there's a topic you're working on that would be helpful to have open in a window by itself, click the pop out icon in the upper right of the topic. easyDITA opens the topic in a new browser tab.

Topic Merge Icon

You can merge changes in individual topics from branch to branch using the topic merge icon.

Note: By default, merging/replacing topics is disabled and the Topic Merge/Replace icon is hidden. To enable this feature, contact a Customer Success Manager.

Source Editor Icon

You can click the angle bracket icon to pop open a topic's DITA source code editor over the easyDITA editor. The topic's source code shows on the left and the rendered editor view shows on the right.

Note: When editing in the source code, your changes will not show in the rendered view until you save your changes. When the source editor is open, you cannot edit in the rendered view.

Resource Information Icon

The resource information icon opens up the Resource Viewer Pane where you can view information about and interact with a particular resource. The Resource Viewer Pane includes helpful information, such as a link to the file's location in the content library, and enables you to quickly navigate to the resource manager.

Commit Changes Icon

easyDITA automatically saves any change you make. If you want to force-create a revision for a particular topic, you can manually create one by clicking the commit changes icon. The commit changes window will open over the topic for which you are creating a revision. When you do this, you can change the status of the topic and leave a comment about the commit.

Note: By default, the commit changes icon is hidden. Contact your easyDITA representative if you would like this feature enabled.

Collaborative Lock Icon

The collaborative lock icon provides a way of seeing how many users are collaborating on a topic. When you are the only user in a topic, the icon shows one individual and is green.

When multiple users are collaborating on a topic, the icon changes to multiple users and adds a number below the icon indicating the number of collaborators.

If you click and hold on the icon, a pop-up opens with the names of all collaborators.

Prolog

Prologs typically display author information, critical dates, keywords, and other important metadata. They can also contain resource ID elements that are crucial for contextual help creation.

Toggle

In the topic editor, you can show or hide the entire prolog by clicking the gear icon and selecting Show Prolog. This action completely hides the prolog from the topic editor.

Collapse and Expand Prolog

You can collapse and expand the prolog content by pressing the Collapse/Expand Prolog (+) or (-) button. This action minimizes the prolog rather than completely removing it from the topic editor.

Figure 12. Expanded Prolog
Figure 13. Collapsed Prolog

Alt Text

You use alt elements to describe images. Inserting alt elements makes your content more accessible to the visually impaired people.

In the topic editor, you can show or hide alt elements by clicking the gear icon and selecting Show Alt Text.

Smooth View

Enabling Smooth View removes breaks between topics and provides a streamlined, long-form document experience.

In the topic editor, you can show or hide space between topics by clicking the gear icon and selecting Smooth View.

Section Indicators

Section indicators are light gray bars that inform you about the presence of sections within a topic. Turning section indicators off provides you with a streamlined, long-form document experience.

In the topic editor, you can show or hide section indicators by clicking the gear icon and selecting Section Indicators.

Outline Placeholders

Outline placeholder elements enable you to quickly insert the elements that are common to a given topic type.

In the topic editor, you can show or hide outline placeholders for common elements by clicking the gear icon and selecting Outline Placeholders.

Figure 14. Context Element Placeholder.

In the following example, the context element placeholder shows under the short description element.

Conditional Content Views

easyDITA enables you to decide how, or if, profiled content appears in the topic editor.

Overview

When you are authoring content it's helpful to see all the content in a topic. Reviewers, however, may prefer to see only the content that meets a specific condition. You can configure how the conditional content appears in the topic editor with Conditional Content Views.

Figure 15. Conditional Content.
The following example shows a piece of conditional content profiled for @audience="userTesting".
Tip: Clicking a conditional content indicator opens the Conditional View Settings Window.
Figure 16. Conditional View Settings Window

Views

The topic editor can show conditional content in different ways.

Figure 17. Show Conditional Content.

By default, conditional content displays in the same way as non-conditional content.

Figure 18. Grayed Conditional Content.

Grayed out conditional content is less prominent than regular content.

Figure 19. Hidden Conditional Content.

Hidden conditional content does not display in the topic editor. Hover over a conditional content indicator to see the hidden conditional content.

Review Tab

Use the Review tab to quickly review documents.

Interface

Figure 20. Review Tab

Operation

All comments for an opened resource, whether that's a single topic or a large DITA map, show in the Review tab. Comments are front-loaded, which means you no long need to scroll through a large map to find topics that have comments, and they are grouped by the topic they are attached to.

easyDITA stores all comments, past and present, for a topic. You can access all current and archived comments in the Review tab by clicking either Current or Archived.

Attributes Tab

Use the Attributes tab to access a list of attributes you can apply to elements in a topic.

Interface

Figure 21. Attributes Tab

Operation

The list of attributes that shows is context-sensitive. By default, the list of attributes contains attributes that are available to apply to the element where your cursor is located.

Outline Tab

Use the Outline tab to see the current and potential DITA structure of a topic. This tab enables you to add elements in valid locations by simply clicking the element you want to insert.

Interface

Figure 22. Outline Tab

Operation

The structure that shows in the Outline tab is dependent on the type of topic you have open. The structure is also customizable. So if you have custom document types with restricted structures, the structure that shows will mirror your document types and only allow users to insert elements that fit within your custom structures.

The elements that are present in a topic show in dark blue, while the elements that are available to add show in light blue. The element where your cursor is currently located is green, giving you a quick visual reference for where you are currently working in the structure.

The Outline tab also shows text preview for any element containing content.

Map Tree

easyDITA enables you to customize the Map Tree pane appearance.

Overview

You can adjust the following Map Tree appearance settings.

Icons Toggle
Enables you to show or hide icons associated with different DITA elements in a map.
Show Elements Toggle
Enables you to show or hide advanced DITA elements like a data element or a reltable element.
Element Names Toggle
Enables you to hide element names, show shortened element names, or show full element names.

Source Editor

To help you navigate the code, the source editor colors syntax and indicates your cursor position with a gray line in the scroll bar.

Important: If multiple users collaborate on a resource, easyDITA places a collaboration lock on the topic and the XML code is not editable.

Map XML Code

easyDITA enables you to edit the map XML source in the source editor.

Figure 23. Map Source Editor.

You click Save to save your changes and close the Edit Source window.

Topic XML Code

The source editor enables you to edit the topic XML source side-by-side with the user-friendly editor rendering.

Figure 24. Topic Source Editor.

You can click Save to save the file and preview your changes. You can also click Save & Close to save the file and get back to the topic editor.

OpenAPI Code

easyDITA enables you to edit the OpenAPI code saved in a JSON file in the source editor.

Figure 25. OpenAPI Code Editor

Markdown Code

easyDITA enables you to edit the Markdown code in the source editor.

Markdown Code

Figure 26. Markdown Code Editor

XML Code Validation

The Source XML Invalid window appears if easyDITA detects that something is wrong with the XML code that you edited.

Operation

Figure 27. Invalid XML Notification
We recommend fixing the invalid XML files immediately because they may result in severe publishing errors. The Invalid XML code is indicated by a red underline and a red rectangle in the scroll bar.
Figure 28. Invalid Code Indicators in the Source Editor

If you plan to fix the invalid XML code later and you don't want to lose your changes, you can save the invalid XML code. easyDITA notifies you about invalid XML files by displaying the Invalid File icon in the content library.

Figure 29. Invalid XML File in the Content Library

XML Code Autocompletion

easyDITA suggests and automatically completes new XML elements for you.

Operation

You can quickly add an XML element by starting to enter the XML element code and selecting the relevant option from the Autocomplete menu. In the following example, the <se was typed and the Autocomplete menu suggested to insert a section element.

Figure 30. Autocomplete Menu

In the following example, the section element was selected from the Autocomplete menu. easyDITA automatically closes the XML elements for you (in this example, the </section> closing tag was added).

Figure 31. Autocompleted XML Element
Important: If this feature is disabled for your organization, contact your Customer Success Manager.

XML Code Formatting

When you edit the XML code, it may become disorganized because you focus on writing and not formatting the code.

Operation

The following example shows a slightly disorganized piece of code in the source editor.

Figure 32. Non-Formatted XML Code

You can make your code more readable by clicking the Format the source icon. This makes easyDITA automatically indent and position the code for you. It is useful if you don't want to waste your time on formatting the code on your own. The following example shows a code that was automatically formatted by easyDITA.

Figure 33. Formatted XML Code

Find and Replace Code

The source editor enables you to quickly find and replace code.

Find and Replace

With your cursor placed in the editor, you can press Ctrl > F (Windows) or Cmd > F (Mac) to open the Find dialog.

Figure 34. Find Dialog

You can set the search to:

  • Match case
  • Match whole words
  • Analyze a part of the file
  • Use regular expression

You can replace your search results with a particular expression. To do so, in the Find dialog, you click the Toggle Replace mode icon that expands it to the Find and Replace dialog.

Figure 35. Find and Replace Dialog

You can replace all search results at once or do it one by one. All search results are highlighted.

Collapse and Expand Code

Some XML files may be very complex, especially if you view their source. easyDITA allows you to collapse and expand elements in the source editor.

Operation

Collapsing some code parts enables you to focus on a given part of the code. By default, all elements are expanded when you open a file in the source editor. The following example shows a concept topic with every element expanded.

Figure 36. Expanded Elements

Imagine that you want to focus on a particular section element in a concept topic. You can collapse irrelevant elements to limit distractions and increase readability. The following example shows a concept topic with some elements collapsed.

Figure 37. Collapsed Elements

Map Editor

You can use the map editor to edit DITA maps.

Interface

Figure 38. Map Editor Pane

Operation

easyDITA automatically saves a document any time there is a change to the file. You do not need to manually save any resource that's open in the map editor.

Context Menu

Right-clicking an element in the map editor pane opens the context menu, enabling you to edit the elements in the map.
Figure 39. Map Editor Context Menu

You can use the context menu to do the following:

Edit topic
Opens the topic in the topic editor.
Edit element attributes
Opens the Edit Properties window to edit the attributes of the selected element.
Edit element XML
Opens the Edit Source window to edit the element XML.
Show file in Content Manage
Opens the content library and highlights the selected file.
Remove element
Removes the element from the map.
Append element
Inserts an available map element as a child of the selected element.
Insert element before
Inserts an available map element before the selected element.
Insert element after
Inserts an available map element after the selected element.
Expand all nodes
Displays all child elements of the selected element.
Collapse all nodes
Hides all child elements of the selected element.

Map Tree

easyDITA enables you to customize the Map Tree pane appearance.

Overview

You can adjust the following Map Tree appearance settings.

Icons Toggle
Enables you to show or hide icons associated with different DITA elements in a map.
Show Elements Toggle
Enables you to show or hide advanced DITA elements like a data element or a reltable element.
Element Names Toggle
Enables you to hide element names, show shortened element names, or show full element names.