VideosFast and Simple Ways to Create and Convert DITA Topics

Overview

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

Transcript

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.

Use Oxygen Feedback to ask us anything about this video.

Products

Features

Shop

Resources

Support

Company

© 2002-2024 SyncRO Soft SRL. All rights reserved.

This website was created & generated with <oXygen/>®XML Editor