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.