VideosWorking with DITA Reusable Components View in Oxygen XML Editor 19.1

Overview

This demonstration shows you how to use the DITA Reusable Components view in Oxygen XML Editor. This view is helpful for DITA documentation projects that utilize a large amount of keys and reusable components.

Transcript

00:00:07In this demonstration, I will show you how to use the DITA Reusable Components view in oXygen XML Editor.
00:00:14This view is helpful for DITA documentation projects that utilize a large amount of keys
00:00:20and reusable components.
00:00:22This view is hidden by default, so if it is not displayed, it can be opened by selecting
00:00:29it from the Window -> Show View menu.
00:00:33The view includes two tabs and it collects all the keys and reusable components that
00:00:39are defined in the root map structure and presents them in a dynamic table where you
00:00:45can easily locate and insert references to them.
00:00:54First I'll show you how to use the Keys tab...
00:00:58Notice that it has a tabular structure with columns that display the key names, their
00:01:04description, the href where the keys point to, and the location of the map file where
00:01:10the key is defined.
00:01:12This Keys tab displays all of your keys and provides ways to easily insert references
00:01:19to them as cross reference links, key references, or variables.
00:01:26Another nice feature that helps you to see where the keys are defined is the ability
00:01:31to group them by definition location.
00:01:34To demonstrate how to use this tab, I am using the oXygen user's manual project, which contains
00:01:40hundreds of key definitions.
00:01:43I have a topic opened where I've identified some content that needs to be replaced with
00:01:48keys and I'm going to show you several different ways to insert them using this view.
00:01:56First off, I've noticed that the name of our product appears at the beginning of the first paragraph.
00:02:02I know I have a key defined for it so I'll use the Search filter to look for this particular key.
00:02:10Notice that the contextual menu includes a "Go to Definition" action that allows you
00:02:14to open the file where the key is defined and see that particular key definition.
00:02:21Now I'm going to replace the product name that is in plain text in my topic with the
00:02:25appropriate key using the Reusable Components view.
00:02:30One way to do this is to simply drag the key and drop it into my document.
00:02:35Note that if the selected key has an "href" value, it is inserted as a cross reference
00:02:40link.
00:02:43If it's a reference to an image, it's inserted as an "image" element.
00:02:47Otherwise, it is inserted as a variable reference inside a "ph" element.
00:02:54I'll briefly switch to The Full Tags mode just to show you that Oxygen inserted this particular
00:03:00key as a variable in a "ph" element since our product key does not have an "href" value.
00:03:08Next, I've noticed that I have the word "perspectives" wrapped in a 'term' element.
00:03:15I know that I have a glossary term for this word defined as a key and in the output I
00:03:21want that term to be a link to that key reference.
00:03:25So, I'll select that whole 'term' element and now I just need to find that specific
00:03:31key in the Reusable Components view.
00:03:34In our documentation project, all keys that were created for glossary terms have the same
00:03:39naming convention.
00:03:41They begin with "glossentry", so I can simply search for 'gloss'...
00:03:48As you can see that all of our glossary terms are listed and sorted alphabetically.
00:03:54By the way, you can change the sorting of any of the columns in this tab simply by clicking
00:04:00on the column header.
00:04:02Now I'll show another method for inserting the key references, so I'll scroll down and
00:04:07locate my "perspective" glossary term... ... and I can simply double-click the key.
00:04:13In this case, since this particular key has an "href" value, notice that oXygen inserted
00:04:20it as a cross reference link inside an "xref" element.
00:04:26There's one more method you can use to insert key references ... by using actions found
00:04:32in the contextual menu.
00:04:34I have another instance of the word "perspective" and this time it's not already inside a "term"
00:04:40element and I want to insert a reference to that same "perspectives" glossary entry.
00:04:46So, in this instance, I'll delete that word.
00:04:49...this time I'm going to right-click that key in the Reusable Components view...
00:04:55...and notice that there are several options that I can choose from...
00:04:59...for my purposes, I'll select "Insert as Keyref"...
00:05:03...notice that this option presents a submenu that lists all the elements that can be inserted
00:05:09at the current cursor position.
00:05:12I want it inserted inside a "term" element so I'll scroll to "more" and select that element.
00:05:22Notice that this time Oxygen inserted the key reference inside the "term" element.
00:05:35Now I want to show you the Components tab.
00:05:38This tab displays all the topics (from the root map) that contain reusable components
00:05:44and it provides ways to easily insert them as content references or content key references.
00:05:51To determine which topics will be displayed in this tab, the DITA Reusable Components
00:05:57view considers topic references that contain a processing-role attribute set to "resource-only"
00:06:04to be candidates to contain reusable components.
00:06:07Futhermore, the reusable components inside these topics are collected from all elements
00:06:13that have an ID specified.
00:06:16These reusable components are displayed in the Components tab along with:
00:06:21- the ID of the container and the ID of the component
00:06:24- the specific name of the element that contains the reusable content
00:06:29- a short preview of the content - the name of the file where the component is stored
00:06:36This tab includes a search field that allows you to filter the text content...
00:06:41some filtering options ... for example, I can choose to only show a certain type of element...
00:06:51... or I can narrow down the list of files
00:06:54by using the Target file field.
00:06:58To demonstrate how the search mechanism works, suppose that I have this section in our User Guide,
00:07:03where it describes how you can move editor tabs.
00:07:07I already have one method documented, but I need to add two more shortcut methods.
00:07:13I know that we have a reusable container topic where we've defined all of our shortcuts keys,
00:07:20and I don't remember the specific name of the file, but I know that it has the word
00:07:25"shortcuts" in its name.
00:07:27So, in the "Target file" field and I'll enter "shortcuts".
00:07:33Notice that the list is now filtered to display only the files that have "shortcuts" in their name.
00:07:39Now I know that the two shortcuts contain the Comma and Period keys, and also that one
00:07:45of the modifier keys is Alt, but I can't remember the second modifier key.
00:07:52Since the search field allows you to use search patterns, I'll use one to help narrow
00:07:56down the targets.
00:07:59This did not narrow it down enough since the string "comma" also matches "Command".
00:08:06So I'll refine my search pattern even more by using double quotes for the Comma string...
00:08:13... and I can refine it even more since I know that "Alt" is one of the modifier keys.
00:08:20This narrowed the targets down to exactly what I'm looking for...
00:08:24So now I'll show you several ways to insert the components in a topic as conrefs or conkeyrefs.
00:08:32In my case, I need to insert a new definition list item...
00:08:37.. and I'll insert the first shortcut just by clicking the Insert link that appears when
00:08:42you hover over the component.
00:08:45Note that if the parent topic of the selected component has a key defined, by default it
00:08:50is inserted as a conkeyref.
00:08:53Otherwise, it is added as a conref.
00:08:57Now I'll insert its description by double-clicking the component.
00:09:03Then I need another "dlentry" ... and this time I'll use the contextual menu action to insert the component
00:09:12... and notice that I can choose whether to insert the component as a conref
00:09:17or as a conkeyref.
00:09:20Another way to insert a component is to drag the component from the view and drop it at
00:09:25the proper location in the document.
00:09:29So, those are the basics for how you can use both tabs in the DITA Reusable Components
00:09:34view to easily insert references to reusable content.
00:09:39And this concludes the demonstration.
00:09:41Thanks for watching!