Changing the DITA New File template

[S3I Staff]

In Arbortext, you can take advantage of the override principle built into the custom directory structure to change what you get when you create a new DITA topic file.

By creating a template file and installing it in the custom directory, you can make your template have priority. Arbortext will use your template instead of the out of the box template when creating new files.

This video contains the basic principles for doing this for the DITA doctypes.

 

[Liz Fraley]

Transcript

Welcome to this episode of the Arbortext Monster Garage. In this video, I’m going to demonstrate how to change what you get when you create new DITA documents. Whenever you create a new document and use the File, New dialog, you’ll have the option to choose Template or Sample. By choosing one over the other, you decide what tags appear in the initial new document. All of the doc types that come with Arbortext Editor out of the box have both a template and a sample defined. You can use them. You don’t have to change them at all. Sometimes, though, you might want to.

Before we go too much farther, this presentation makes the following assumption. You have configured your custom directory according to best practices as described in my book Arbortext 101. If you haven’t, these instructions may be confusing to you. However, I am confident that if you familiarize yourself with the best practices classes defined in Arbortext 101, you will be able to connect the dots. You’ll be able to apply the lessons you learn in this video to your own environment.

If you watched the DocBook version of this video, you can skip ahead or review the basic principles of Arbortext that make this work.

If you don’t know where to find Arbortext 101, all you have to do is go to http://arbortext.training. The links to all of the Arbortext Monster Garage books, videos, and other resources for help can found there. I’ll talk more about this at the end, but for now, let’s get started.

Back to that File, New, Document dialog box. When you want to create a new document, you start by choosing the doc type you want to create, and then you optionally choose template or sample at the bottom of the window. Choosing one or the other changes what you get.

For example, if we choose data concept with the template radio button selected, we get a pretty empty data concept. There will be tags present that are common to well-written data concept topics, but the tags will be empty. We have a structure without content. The same is true for all the topic types.

By selecting the Template radio button, you get a new document that contains very basic structure to get you going. Think how much work it would be if there was nothing there to get you started. That’s what choosing Template does.

Now, what about sample?

If instead we choose DITA Concept with the Sample radio button selected, we get an example DITA Concept, complete with the content in it. Samples are great for new users. It’s an example of a good DITA concept.

There are graphics and figures and tables and lists and cross-references, all of the things that a seasoned technical writer employs, but a new data writer may not know exactly how to build or what tags to use to achieve it. Both the template and the sample serve a purpose.

In a nutshell, this is the difference between template and sample. A template is a partial instance. It’s a starting point. It can have tag structures, it can have typing, it frequently has comments or advice. It’s a template in the truest sense of the word. It provides a basic structure for the user to start filling things in.

A sample, on the other hand, is an example. It is typically complete a demonstration of what a good well-written example of this document should be. It’s a demo. Here’s an example. If you see, the template has empty tags, much of them already in place. All you have to do is start filling in your content.

The sample, on the other hand, is already full of text. It’s got content. It’s a demonstration of a good written example of the concept. Make sense?

Now, you can keep the out-of-the-box versions, or you can change them. You don’t have to use the structure that Arbortext defaults to. You can create a template that is more representative of the content you write every day.

It is the Custom Directory that helps you isolate, protect, and save your preferences. That’s what it’s there for. We’re just adding another tool to your Custom Directory toolbox. If you create a new template file and put it in the ditabase directory, and make sure that the DCF file is adjusted so the editor knows what template goes to what data doctype, then your templates will override the out-of-the-box templates. As simple as that.

Let’s walk through the overall process and then we’ll do it. Generally, this is what we’re going to do. We’re going to create three new template files and install them in our custom directory. We’re going to make sure Arbortext Editor knows which file applies to which topic type, and that’s all specified in the DCF file. Then we’re going to test that our versions override the out-of-the-box versions. We’re also going to take a closer look at that DCF file so that I can show you what parts apply to the template and sample behavior in Arbortext Editor.

Sounds pretty simple and at it’s base, it really is. But it’s just the beginning. Doing things with template and sample files can have dramatic effects on our productivity. Once you open your mind to the possibilities, you’ll be surprised at what you can do.

But that’s for later. For now, let’s get the basics down.

First, let’s locate that custom directory. In our Custom Directory, this is where the DCF file is. It’s also where we’re going to put our new template files. Let’s open that DCF file in Arbortext and take a look around. I’m just going to right-click on it and open it.

You’ll notice in this file, there’s an element called new dialog. This is the element that controls what happens in the new dialog box. Let’s expand the element and take a closer look. You notice there are several new elements in the new dialog, and each of them have a sample file attribute and a template file attribute.

Each one of those attributes has a value. That value is specifies the name of the file, the specific file, and its name to be used in each case. In this case, for DITA Concept, if I click the Sample radio button, I’ll get a new file based on the conceptdemo.dita file located in the install tree.

If I click the Template button, I’ll get a new document based off of the concept template.dita file also based in the Install tree. Those files right now are not… We don’t have anything like that in our custom directory. These two files are located in the install tree. So we’re going to have to change this DCF file once we have our new templates created.

This is the basic principle of overriding behavior that I discuss more thoroughly in Arbortext 101. It is because of the way the DCF file wires the override behavior that we can make make changes simply and without excessive customization that’s expensive to maintain over time.

Okay, so let’s close this file and go make our template files of our dreams.

From the file menu, we’re going to choose New, and this is what we’re going to be changing. So let’s choose Concept Template. We’re going to leave that button selected because that’s what we’re changing, and click Okay. This is an instance of the out-of-the-box this template for a standard DITA concept.

To make things simple, we’re going to change this stuff here at the beginning. It’s easy, it’s obvious, and it will demonstrate the point of the exercise well.

We’re going to delete the prolog. That’s the only change we’re going to make, and we’re going to save this file to our desktop. We’re going to name it templateconcept.dita, and we’re going to save it on our desktop. Why give it this name? Because we’re going to make We have several of these and we want to be able to differentiate. We also want to make sure that we have a common, simple name structure that we can use when we’re editing the DCF file.

Now, let’s do the same for task and reference file. File, new. Let’s pick task. We’re going to make this a much simpler task. We can get rid of all these extra things, and we’re going to leave context and steps and leave it at that. We’ll file save templatetask.dita. All right, one more. Let’s do reference, file, new, dita, reference. Okay. This one we’re going to simplify, too.

Reference is typically the one topic type we are most often requested to have changed. It’s just reference topics have a high variety across customers, and not everybody uses all of these things.

I’m going to make this really simple. I’m going to leave one section that’s basic. I’m going to get rid of all the extra kinds of things, and we’re going to make a very simple reference template. We’re going to save. ditareference.dita.

All right. Now, we’ve got our three files. Let’s put those three files in our custom directory. Now let’s open that DITA doctype the DCF file once again, and open our new dialog.

Now, if you’ll notice, there’s two entries for DITA concept. There’s two entries for glossary, there’s two entries for reference task, et cetera. You’ll notice, too, that one of them is the the XSD version, but it’s also suppressed. When we do the file new window, we’re not seeing the data concept XSD. We’re just seeing DITA concept. We only need to change that one. If we want to switch things out and deal with the XSDs, that’s a whole other video.

But for now, this is how you differentiate. What it says in the description is what it shows up here in the type line, and that’s the one we’re going to change.

We changed Concept, that’s this one, and we changed the template file. We named it Template Concept. Now, let’s look down and find the next one.

Here’s Task. We changed that one. We called it Template Task.

Then we’ll go down, let’s see if I can’t find reference. Sometimes I go right past it. Here we are. Reference.

Now it’s going to look for files that are local to this file. There’s no path other than the local file reference name. Those are here. The names are the same. We should be able to see our files override the default behavior.

Now, we do have to close Arbortext. We’re going to save our DCF file, and we’re going to close We’re using the Arbortext, not just the file, but the Arbortext itself. Why? Because we’re changing our custom directory. We’re changing fundamental behavior of the dialog boxes. When you make those kinds of changes, you have to restart Arbortext. You cannot change its configuration out from underneath it.

All right, so let’s relaunch Arbortext, and let’s see what we get. File, new, DITA technical content, concept, template, and what do we see? And there’s our concept, the much simplified concept without the prolog.

Let’s try the other two. There’s our simplified reference topic, and let’s see our task. There’s our much simplified task.

Pretty easy, pretty straightforward, and we’ve got what we wanted. Now, these new files are based on the structure we created and installed into our custom directory, and all we had to do was wire up the DCF to tell us which was which. Don’t you love it when that happens? Everything just works. That’s it.

In the next video, I’ll show you how you can create multiple templates for the same document type. Do you have three or four different reference topics you write all the time with slightly different structures? All you have to do.. You can create multiple templates and configure editor so that you can choose them explicitly. It’s a little different, but not any harder. And it’s so, so very useful to groups who want to the author template structures and reduce those repetitive stress, injury, encouraging, repeated actions. Why should you have to fix the template by hand over and over every time you create a new topic?

That’s what the templates are for. That’s for next time. The last thing I’ll say is this, never struggle for more than 30 minutes. My personal rule of thumb is to set my time limit for fighting with anything to 30 minutes and never ever any longer than that. If I can’t figure out in that time, I write it down, put it aside, and go on with my work.

Sometimes you need to let your brain rest and come back to a problem fresh. Spending more than 30 minutes struggling with something, and you’re wasting your time and money. Give it some time to do something else. Write it down to be sure. You might also write down notes on what you tried and what you figured out or didn’t, so that when you come back to it, you’ll be able to pick it right back up, or you’ll be able to explain it quickly to someone else.

Our customers do this. They know not to go more than 30 minutes. To make time with me efficient, they keep a list, and when they have enough questions, they book some time with me to work through them one after the other.

And now you can do that, too. Remember that Arbortext training page? Well, each subject has a link right there for you to get help. You can limit your time and your spending and still get as many questions answered as you have queued up. Don’t struggle.

Hopefully, this video and the others help you enough on this topic. If not, don’t forget you can book time with me, too. Thanks for watching and good luck.

[Author]

Posts