Working with DITA Maps in Arbortext

[S3I Staff]

In Arbortext 7.0, creating, editing, and manipulating DITA maps is easy to do! In this TC Dojo: Arbortext Edition, we cover the basics for creating, managing, and using maps in Arbortext Editor.

We show you how to insert all kinds of DITA content: Topics, Concepts, References, Tasks, other maps and more!

We explain the Resource Manager, several ways to create new topics and manage or insert existing topics.

If there’s time, we will discuss how you can create your own templates to create stub documents that get you started quickly creating standard information structures.

By the end, you’ll be a pro at working with DITA maps in Arbortext.

[Liz Fraley]

Transcript

Welcome to the webinar today we are going to show the basics of working with DITA Maps in Arbortext.

I’m Liz Fraley the CEO and founder of Single-Sourcing Solutions. I’m a consultant, but here at Single-Sourcing, we take a slightly different approach than other consultants. We don’t usually do your whole project for you. Well, we can do that, we prefer to take more of an apprentice to journeyman approach. Do you remember back in school when you were in the big lecture class and listening to the professor? Maybe you asked your questions there, but most likely you waited until you were in discussion section and asked the questions of your TA.

That’s what we are. We are XML, DITA, Content Strategy, and Document Analysis TA. I mean, you’ve read all the books. You’ve watched all the videos like this webinar is going to be. But you still need someone to ask questions to. You can’t ask questions of a book and you can’t ask questions of a video. It’s been said that I give information away like Candy and I do. I’ve been doing this for more than 15 years. I’ve used nearly every tool out there, I have done XML, HTML, DITA, Docbook, even S1000D

And if you know anything about me, you know that I have a ton of community service projects all going at the same time. I founded TC Camp the unconference for Technical Communicators, which started as an experiment and had 160 people that first year. We’re now on our fourth and have spun it out as its own non-profit and I still serve on the board. Observing the board for the San Francisco Bay Area ACM, the Professional Organization for Computer Science people, because I have a B.A. in computer science also. I’m the program coordinator for the East Bay STC. A professional organization for Technical Communicators because of my deep experience doing all things techcomm related. And I love to get others to tell their stories and share their experience. Well I’ve been through it all, from the customer side long before I became a consultant, I learned from others and now I share my experience. And that’s what webinars like this one today are all about. It’s all about you. You’re here to learn about DITA Maps and Arbortext.

So enough about me. Let’s get started. Today, we’re talking about DITA Maps. How to create them, how to edit them, how to manipulate them using Arbortext. I’ll show you how easy it is to publish into, towards the end of the session. Right now, I’m going to switch over to Arbortext. Let me get that all setup and running. And, here we go. I’m using Arbortext 7.0 first release, it’s currently available. It came out just a few months ago and we’re going to get started with Maps, this is the beginning. We’re going to use some sample content that comes with Arbortext out of the box. Arbortext includes this content as a way for you to exercise the DOCTYPES and the content model in a way that lets you try things out without having to work on your real life documents. It’s a great way to get started without having to start from pre-scratch.

You get to start with the flower, not the leach. So first we’re going to create a Map. And there’s three ways to do this. I can click the New icon up here in the toolbar. I can choose File, New or I can use the keyboard shortcut Ctrl+N. I’ll click this button. All three cases, bring up the new document dialogue and you’ll see there are categories in the left-hand side making it easy for you to choose the type of document and its content scheme that you’re interested in.

We’re interested in DITA technical content and we’re interested in Maps. I’m going to show you the Book Map and we’re going to use a template. This is what the basic Book Map looks like out of the box. When you’re working with Arbortext, the sample content. I’ll show you that a little bit later. But right now, let’s start with the Map. All right, here we go. And I have my typical deployment is I look at Maps from a two-screen process. I can see the outline view up here at the top, the column view is called because it’s got all the columns for all of the attributes for anything that DITA Map. Making it really easy to edit, and this edit view down in the lower half of the screen. Now, I don’t have to see it this way. I can turn this Top Bottom Split off, make it No Split and I’ll see the outline view

Usually, you turn the Resource Manager on when you’re working with DITA content. I had it off earlier, so here it is off. Arbortext will preserve whatever environment you prefer to work on. So right now, I have the top menu bars with the icons this is brand new in 7.0. They’ve all been updated and simplified a bit here in the toolbars at the top. I get the column view over here in the main center of the screen.

And this is, all of the attributes that you might apply to any DITA Map element, you can see them all in one place. You can see them all at one time and just scrolling over a little bit at a time, will give you all of the attributes. If you want to view one of your topic to different language. Do you want to change the collection type, drop things in or out of the TOC, make it available for print, but not for Web?

You can change all of those attributes right here in, the audience, the platform, your key names. You can change it all right here in the outline, In the column view. Now, let’s say we want to create a new topic and we want to put it in our Book Map. Now, Book Map is a special kind of Map, you can insert things at the top level to where our cursor is. And you can choose to insert it as a Chapter or a Part or a Volume.

Right. We have any kind of choices. We can choose it as an Appendix. We can choose it as the appendices part, just like a part or a chapter. We want to create a new topic here, not insert an existing one. And it works very simply. I can put the cursor where I want it. I’m going to insert a new chapter because here I am in a Book Map and I’m going to choose a DITA concept. Let’s give it a title.

Overview, if you notice, when I type in the title, it automatically types in a file name. If I had a Keyref, if I could choose it right here and insert it myself and let’s decide where we’re going to put it. And we’re going to set our default library location to be a folder on the desktop called MyManual. And then what we’re going to do is we’re going to click the insert button. Automatically, we get that overview chapter inserted into the Map. We get the title that we chose automatically inserted into the attributes for the Nav Title.

We get the location set up correctly. We get the type automatically inserted. The scope and the format are the typical defaults for DITA concepts in your Map.

Great. Now, let’s say we want to insert another topic, but this time we’re going to insert a Task. TaskTheFirst. And it’s still putting it in my folder, it’s inserting it as a topic ref, not a Map. Because it’s not a Map we are inserting a topic type, we’re inserting our task. All we do is push insert. And there it is. It’s inserted where our cursor was, which was inside the chapter. So now we have  TheFirstTask inside the chapter we have the concept topic as the chapter initial topic.

Great. So we have all of these, all of this working out. Its a really easy way to insert our topics right into the Map. Although now say, we want to change the Main Book Title, that’s the template code. So this is what your Main Book Title would be. But we want to change it. We want to set it to what our actual topic is. There’s three ways to do it. We can do the Top Bottom split so that we can see the main book title and change it.

I can change it right there or say I didn’t want to do it that way and we change it to, we change it back to No Split, we come back to the outline view. We can change our view to the Edit view. Now, we don’t see the outline anymore. We get this view and we can turn the tags on or off, depending on what we want to see, really. We always use the Topicref because in the Map, that’s really what the code says.

But say we want to see what those tags look like, what the actual code says. Well, here we go. What we see, we don’t ever have to type in the tags because we already know what the schema allows. So Editor just inserts those tags for you. All you have to do is put the cursor where you want things to be. So here’s our topic inside our chapter topic. And here’s our main book title. Let’s turn it back to the column view. And we will see that the map is automatically updated and let’s split our window back again so that we can see everything and we don’t really care about seeing the tags at the moment it could be handy if you just want to see where the tags start and stop.

So you can see this is main book title, but this is book title. You can see the cursor is moving in the Map to show you where you’re at and this shows you where you are too. The boundaries of the of the tags we can turn them completely off because it really doesn’t matter. You’re seeing this first page break text right here. That’s because that’s the ineditor stylesheet at work. That’s just the one that comes out of the box. It does not have to be there. The first page break is really just an example of the stylesheet, just like you get the sample content.

All right. So let’s now. So now we’ve created new topics and we see how easy that is to do. But say we have a topic we want to insert. We already have a topic. And I’ve got this whole manual full of topics over here. We can now, instead of creating a new topic in our Resource Manager. We go to the topic tab, we look right where we want to find it? Here’s our manual, here’s all the possible types we can have. We’re going to insert only topics. We’re not going to insert a Map. And we’re not looking for an image at this point. And we’re not inserting a PDF image, which we could do because Arbortext, we’ll let you use a PDF to insert in your Map and it’ll insert those pages right along in that location. So let’s put, here’s a great one configuring column view, very handy tips.

This is the sample content that comes with Arbortext out of the box. We can see that it’s a test type and we’re just going to insert it right there in our chapter. That was pretty easy. We’ll say. Now, we didn’t mean to put it here. We didn’t want it to be a sub topic of the overview chapter. We wanted it to be the top of the new chapter. All we have to do is move it, move it to where the cursor allows it to be placed.

So you can see there’s a plus, blue plus sign next to the arrow icon to the mouse. You can see behind it there’s a little blinking grey indicator showing you where you’re moving it to in the tree structure. As long as the blue plus, that means you can do it and it changes it automatically to chapter because we’ve already got the chapter structure in our Book Map. Let’s say we didn’t mean to put it there, let’s put it in the Font matter instead.

Looks just fine now, let’s say we wanted, we had a topic we wanted, the other way we can do it is we can cut and paste. We can either use the icons or use the standard Ctrl+X and Ctrl+V, and that moves our task down to that matter.

Multiple ways to do it, any of them work just fine. Insert topics by looking this way or through the other way. If you had Arbortext content management here, it would show up in your drop-down menu as your content management database. And you could navigate or search for the topics that you wanted to insert into your Map. But we’re saving Arbortext content manager for another day. This is showing you just strictly filesystem management of all your topics. OK, so that’s how you insert topics into a Map.

And let’s save this off just on the top of our content. Because I’m crazy saver I save things all the time. We showed you how to use the tag view for tags, how just to see the tag boundary. This is what we call partial tags or turn tags off completely. You can cut and paste, you can drag and drop. You can move topics around in your Map. You can insert topics that exist where you can create brand new topics straight off the fly and it will create the topic for you.

So remember, this overview chapter was one that we created brand new through the new topic dialogue. And while it inserted into the Map, we want to make sure that it created the file as well. We can do it, open that topic in two ways. We can just double click right here on overview, and there’s our topic. Right, again, we have the tree view here on the left. This is what we call the document view, Document Map View.

Over here, we have the Edit view in the right-hand pane. Again, we’re not seeing any tags. We’re not seeing any boundaries. We can just start typing.

And we can start the next paragraph here is the next one. Say we meant to have this be bullet, because its turned that right into a bulleted list. We can turn it into a numbered list. We can turn it back into a paragraph. We can add more paragraphs. We can turn off the list, and then it goes away. Anyone of these things, this is the second tag in a list item. Now, let’s say I wanted to do another list item, there it is, list item.

All I’m doing is hitting the enter key and up pops the pop-up menu of tags that are available at this point in time. It will offer, these are below the line. These are elements that are in line text. These are inline elements that you insert along inside the paragraph that you wanted to add a UI control now. Here’s the UI control. Right, so that gives you the option of having where it is.

So you noticed this changes based on where your cursor is. And if you see over here, our cursor, the little grey arrow is inside the UI control tag. So these are elements that are allowed inside the UI control tag. Or it gives you the option above the line to create the next list item. Just create another ordered list to insert another paragraph in our list item or to add a whole other list item. It lets you figure out, it’s a quick way to give you the options to do whatever it is you’re trying to do next.

So, but here we go, we have all the same information we want to have, what goes in this template version of the new topic type, a new concept, a new task, a new reference is completely configurable. We’ll save that for another time. But here we go. An easy way to see our topic and open it and change it. If we wanted to, we could always open it this way I forgot what we called it, Overview.

I believe that’s what we called it. And there’s our topic this way. OK, so easy to open up a topic that you’re working on and work on that topic and then close the topic. Easy to insert topics into your Map. Easy to move them around. And it will automatically change its topic ref tag type based on where you place. But where you’re moving your topic and following the rules of the DOCTYPE, right. Again, if I move this topic up so that it is a sibling of chapters at the same level, it becomes a chapter.

If we move it into a chapter, it’s no longer a chapter, it’s back to being a topicref, automatically doing the work for you. Right, because editors are well aware of the DOCTYPE and you don’t have to do all that for yourself.

OK, so there’s one more thing to show you, and that’s the resolve document type. And this has been around since wanted to say five-four and that’s a very long time ago. And it’s this way in the edit menu, you come down here to the bottom, edit resolve document for editing.

There’s a styling option too. But we will save that for later because we’re not styling the document today. We’re editing in it. So we open it up for editing. And what it’s going to do is it’s going to compile a composite schema. It’s going to resolve all of the DITA information and it’s going to give us the entire document all as one. Now, we don’t really want to see this outline top part. We just really want to see all of our information in context.

So we’re going to turn off the split. And here’s what we have. Unfortunately, I did that from the task, the first topic. So all I’m getting in the resolved document is the task. The first half, if I want to see the whole book in context, I make sure we’re up here at the Book Map so that we’re resolving the whole thing. That means I could resolve just the chapter where I want to resolve the whole Book Map. I will do file edit resolve document before editing again. It’s building the entire document.

We’re going to turn that Top Split off. And here is our entire document. There’s the column view topic, here’s our overview and our TaskTheFirst. If you’ll notice two things are happening here. We get a dotted line that indicates where the file that’s being, that is represented by that topic starts and ends. This is the boundary of the concept topic. We can see the dotted line around it. Same for the task.

We get the dotted line around the task where its boundaries are. And you’ll see this one big dotted line all the way around, because this is the other topic that we inserted from the sample content. See, we want to change it. This is all editable because this is the resolve document for editing. So we’re going to change this topic title into By Liz. You’ll notice the first thing that happens is our dotted line became solid and we got this key.

This key means we’re editing the topic. It’s checked out in a way to us. It’s locked in the file system for us to edit. No one else can edit it until we release it. Now we’ll push save back to a dotted line, back to a box, and our task is updated. How do we know that for sure? Let’s close our resolve document type, come back to our Map and open our topic. And here it is back to being exact the same changes we had before. And I’m going to change that because I want to. Great.

So this is the basics for working with Maps in Arbortext. You can add the structure by hand. You can if you wanted to, you can insert topic groups topic heads just by clicking the Enter key. We can insert what we want to have, the one that’s really handy here, and that is key reference points. The key definitions. And we’ll probably do a whole another session about how to work with keys or insert keys into your Map and how to use them, but as it is for here right now, you have it.

And there’s also you’ll see that there’s a key definition to have up here to say we want to insert a new topic element a new keymap, choose what we’re going to do here and insert a new topic. And you can just construct your key right here on the left-hand side. But we’ll get into that in another session. I just want to point it out here, because it’s a super-easy way to get your keys created and inserted, running your Map.

All right.

So just to recap, you don’t have to look at the tags. You can turn them on off or somewhere in the middle. I like them on because I like to see what I’m doing. Not everyone likes to. Up here, you can insert, let’s insert a Reltable. Here’s a typical setup where your column ones are concepts, tasks and reference. We’re going to have the troubleshooting one. We automatically insert our Reltable and here’s what we get.

So one of the nice things about Editor is if I want to put this task in my Reltable. And I want to put it in my Reltable. I don’t have to put it usually you would by hand put it here in the task column, but say I’m just down here and I click accidentally in there and I push paste, notice what happens, because it knows that it’s a task. It puts it in the task column for me.

It doesn’t put it accidentally in the wrong column, and that’s very handy for sure. And again, I could copy and paste and there it goes right into there. Let’s take this one drag and drop right into our table. I’ll just drag it into the table and it automatically puts it in the right column. Closest to where my mouse was, and that’s pretty much how it works. Very easy to use, Maps are simple and complicated, but they’re also very powerful and you’ve got a lot of power behind you right here in Editor.

You see your column view, you can see the edit view. You can turn the tags on and off. You can split your screen or not. You can use this resource manager in your left-hand side to create new topics, to insert existing topics. And if you have content management, you can, there’s the adapter, once you turn it on, will connect directly to your content management system for insertion of topics or anything else. All right.

I think we’ll save the next part. How to create concepts, how to create tasks and how to insert content into good DITA topics. We’ll save that for our next session. In the meantime, thanks for attending. And if you have any questions, let’s see what that looks like.

So by now, you see how easy it is to use Maps edit, create and manipulate DITA maps in Arbortext, and if you have any questions, be sure to contact me.

Like I said, I give information like Candy we do these webinars all the time. We’re going to start doing one a week little basic tutorials on how to use different features in Arbortext. And I hope you join us. We’re going to go to questions, but I’m going to end the recording here. Thanks, everyone.

[Author]

Posts