VideosFast and Simple Ways to Create and Convert DITA Topics


This demonstration shows you the fastest ways to create new DITA topics and how to convert existing DITA documents to another type.


00:00:07In this video demonstration, I will show you the fastest ways to create new DITA topics
00:00:12in oXygen and how to convert existing DITA documents to another type.
00:00:18For this purpose, we will use an existing gardening DITA project.
00:00:26The first method for quickly creating a new DITA topic in oXygen is to use the new document wizard.
00:00:33I could, of course, start this wizard with the toolbar button
00:00:38but at some point I would still need to add it to my DITA map structure
00:00:42so it is better to invoke the action from the contextual menu in the DITA Maps Manager
00:00:47and a reference to the new topic will be added to the DITA map according to the context of my selection.
00:00:53I'm going to choose to invoke the action from the "Append Child" submenu so that the new
00:00:58topic will be added as a child of the current selection in the DITA Maps Manager.
00:01:03In the New document wizard I'll select a file template for the type of DITA topic that I want to create.
00:01:09I'll enter a title so that I don't have to
00:01:12do this afterward and I'll select the "Use the title to generate the file name" option.
00:01:19Notice that the file name at the end of the path in the "Save as" field
00:01:24changed based upon my title.
00:01:26Also, you can click the "File name generation rules" link to configure the rules for how
00:01:31oXygen will generate the file name.
00:01:34I will also leave the final option selected because this will assign my file name as the
00:01:39root ID for my new topic.
00:01:41After I click the Create button, the new topic is created and opened in the editor.
00:01:47Note that some very basic content is already populated for me, and a topic reference is
00:01:52added to my DITA map structure in the DITA Maps Manager.
00:01:56Now we'll fast forward, supposing that we finished adding content in this topic.
00:02:01This method is great if you just want to quickly create a new topic with a very basic structure
00:02:07and no content beyond the title.
00:02:14The second method is even faster and will save you a lot of work after the topic is
00:02:19created but only if you have an existing topic that has a similar structure or similar content
00:02:25to what you have planned for the new topic.
00:02:29In my case, I have an existing topic about a certain type of flower and I want to add
00:02:34a new topic about a different flower but the new topic will end up being very similar to
00:02:39this existing one.
00:02:41So, all I have to do is to invoke the "Duplicate" action from the context menu.
00:02:47In this dialog box, I just need to change the name of the file and click "OK".
00:02:54This action created a duplicate of the existing topic with a different name, then opened it
00:03:00in the editor, and it created a topic reference to it right after the existing one in the
00:03:06DITA map structure.
00:03:08If this was not where I wanted it in my DITA map structure, I could of course move it,
00:03:13but in this case I'll leave it there.
00:03:16Now I just need to edit the content of the new topic, which in this case will be much
00:03:20easier than creating it from scratch.
00:03:24As you can see, this method is great if you have an existing topic that is the same type
00:03:29and has a similar structure to the document you want to create.
00:03:38The third method that I want to show you is a feature that allows you to quickly create
00:03:43multiple skeleton topics at once and you can easily specify their structure within the DITA map.
00:03:49In my use-case, I need to add a new chapter in my documentation and I've planned out its
00:03:55structure in advance.
00:03:57I know what the hierarchy of my new chapter will look like and I know the titles for all
00:04:02of the topics.
00:04:04Basically I want two new chapters - Autumn Flowers and Winter Flowers - and a couple
00:04:11of topis in each of them.
00:04:13In the DITA Maps Manager, I have decided to insert my new chapter after the "Summer Flowers"
00:04:18chapter, so I invoke the "Fast Create Topics" action from the context menu.
00:04:23In this dialog box, notice that there is a text pane that has an example of a hierarchy of topics.
00:04:30I'm going to change this to the structure that I planned out in advance.
00:04:34Here I can paste the file structure that I copied from a table of contents ... or edit it.
00:04:42Note that you can use the Tab or Spacebar keys to insert indents and this allows me
00:04:47to create a whole hierarchy of topics with multiple levels.
00:04:51The titles that I enter in this text pane will not only be used for the topic titles
00:04:56but also to generate their file names and I can click the "File name generation rules"
00:05:02link to configure the rules for how oXygen will generate those file names.
00:05:07I'm going to leave the "Use the file name as the value of the root ID attribute" option selected.
00:05:13This will use the file names to automatically assign root IDs for each of the topics, again
00:05:19so that I don't have to do it afterward.
00:05:22All of the topics that will be created will have the same Topic Type.
00:05:26I can change it if I want to, but I'll leave it at the "Topic" type.
00:05:30Now, don't worry if you're thinking you would rather be able to choose multiple topic types
00:05:35in this dialog box because in a moment I'm going to show you another feature that will
00:05:40allow you to easily convert them.
00:05:43For the last option, I'm going to select "Siblings" because I want my new chapter to be inserted
00:05:48after the current selection.
00:05:51Then I click "Create" and notice that my new chapter and its entire structure was created
00:05:56in the DITA Maps Manager.
00:05:58Also, note that the newly created topics have only a basic content.
00:06:04As you can see, this method is great if you want to quickly create a whole structure of
00:06:08skeleton topics that you'll add content to later.
00:06:17Now I'm going to show you how to convert an existing DITA document to a different topic type.
00:06:23Suppose that I realized that my Garden Preparation document should have been a DITA Task, rather
00:06:28than a Topic.
00:06:30oXygen includes some refactoring actions that allow you to quickly convert from one DITA
00:06:35type to another.
00:06:37There are several ways to access these actions.
00:06:40If you want to convert multiple documents at once, you can select them in the DITA Maps Manager,
00:06:46right-click, go to "Refactoring", and choose whichever action is appropriate.
00:06:52Suppose that I just want to convert a single document that is opened in the editor.
00:06:57To see that the structure of the XML document changes from topic to task, we'll switch to
00:07:03Full Tags mode.
00:07:06Note that currently our DITA document is a topic.
00:07:09Now...I can simply right-click anywhere in the main editing pane, go to "Refactoring", and choose
00:07:16to convert it to a DITA Task.
00:07:19You could click "Finish" to process the conversion immediately, but I'll click the "Preview"
00:07:24button just because I think it's always a good idea to preview these refactoring operations.
00:07:31I don't see any glaring problems with the changes that will be processed,
00:07:36so now I'll click "Finish".
00:07:38Behind the scenes, oXygen will map the structure of the previous DITA document type to a structure
00:07:43that fits the new type.
00:07:46Notice that my topic has been converted to a "Task".
00:07:50Now we switch back to the partial tags mode to unclutter the editing area.
00:07:55In some cases, especially when the previous structure was very complex, the conversion
00:08:00might result in an invalid structure where some manual adjustments are required.
00:08:06In my case, I simply need to remove an invalid element and I can easily do this by using
00:08:12the Quick Fix feature which was automatically triggered.
00:08:15The great thing about this feature is that it keeps your content intact and saves you
00:08:21a lot of time by mapping the element structure for you.
00:08:24The alternative would be to create a new DITA Task document and then copy and paste the
00:08:29content one block at a time and in many cases, this would be much more time consuming.
00:08:38And this concludes our demonstration.
00:08:39Thanks for watching.