Did you know with Arbortext, Specializations require no additional programming?

Did you know Arbortext ships with easily customizable stylesheets to support output to multi-channel output formats (HTML, PDF, RTF, etc.)?

Did you know PTC now has the only fully-functional, end-to-end, enterprise-level DITA solution: Arbortext Editor, Publishing Engine, and Content Management System?

Did you know Arbortext 5.4M50 was released June 1st with full support for DITA 1.2 even before 1.2 was released for public comment?

The OASIS DITA standard began with IBM and it began in Arbortext. PTC/Arbortext was the only vendor invited to be a charter member of the Oasis DITA Technical Committee and participates on that committee today.

In this one hour websession and find out how easy it is to create DITA stylesheets in Arbortext.

Who should attend: Anyone interested in moving to DITA now or in the future, anyone who has already begun that transition but is looking for a better way, and anyone who is just plain curious.

TC Dojo Expert-In-Residence

Liz Fraley, Single-Sourcing Solutions, is a serial entrepreneur. She’s founded two companies, sits on the boards of three non-profits, and is constantly coming up with new ways to share knowledge in the technical communications and content industries. She has worked in high-tech and government sectors, at companies of all different sizes (from startups to huge enterprises). She advocates approaches that directly improve organizational efficiency, productivity, and interoperability. If you ask her, she’ll say she’s happiest when those around her are successful.

Watch the Video

Recorded: August 2010

Transcript (Expand to View)

[00:00:03.700] - Liz Fraley

Before we get started, I wanted to give you a brief agenda about what I'm going to cover, I have a few slides just to give us a little context. But we're going to spend most of the presentation in demonstration.

[00:00:15.430] - Liz Fraley

Arbortext has been around since the early 1990s and has a long history with SGML, XML, and DITA. It's one of the first commercially available SGML editors. People argue over exactly who is first, but that's not our concern here today. It's the editor IBM was using when they developed DITA and R&D folks from Arbortext have been part of the OASIS DITA technical committee since its inception.

[00:00:39.480] - Liz Fraley

Arbortext is the only out of the box end to end solution since the acquisition by PTC in 2005. Arbortext has been focused on making sure that products are integrated and play nicely with each other. We've all heard horror stories from publication groups who've had to duct-tape a solution together in order to get the full solution, and oftentimes despite years of work, they never really fully realize the capabilities of a complete end to end solution. As a result, PTC has been hard at work smoothing user experience so they can focus on delivering content without having to become software developers too. They push hard for real interoperability cooperation between applications because this is what their customers have asked for. What a lot of outsiders don't know is that PTC product development is guided by a customer-driven technical committee and customers have a lot of resources available to them as well. But we'll talk about more of that at the end.

[00:01:34.440] - Liz Fraley

Very briefly, this is what the system looks like to an Arbortext customer. It's a very simple diagram, not a lot of moving parts. All the pieces know how to talk to each other out of the box. Today, we're just going to talk about Styler.

[00:01:47.980] - Liz Fraley

This is Styler, it's a UI to simplify stylesheeting and make non- programmers capable of maintaining and creating stylesheets. Well, let's move on to the demonstration.

[00:02:10.040] - Liz Fraley

Today, we're talking about how to use the Arbortext Styler product to work with the DITA stylesheets. The way I thought we'd do that is to look at some best practices. It will be a short presentation, will touch on the resolved document for styling that we use and how to create a new stylesheet, the location of the existing stylesheets, and how to work with the out of the box modular stylesheet architecture. There's a fair amount of documentation around Styler and some specific documentation on using Styler with the DITA application. What I'm going to cover today is a recommended best practice on how to get started. Hopefully, this will help people get familiar with the product, and really the best way of creating new stylesheets.

[00:02:49.180] - Liz Fraley

I have open on my screen Arbortext Editor with Styler. And today we're going to use the Styler product to create a stylesheet. This stylesheet can be used to create output for multiple formats such as print, PDF, HTML.

[00:03:01.780] - Liz Fraley

So we're going to start by creating a new document. We'll go up to File-New, and we'll select DITA book map and we'll create a sample. This is going to be the starting point for my stylesheet creation. This document would be a document that contains a lot of the different examples of formatting that you would want to have represented in your output. When you create a style sheet, you're basically defining the rules for how these elements are going to appear in the various contexts in the output. You want to have a document that represents the vast majority of constructs that you would see in the various outputs.

[00:03:41.820] - Liz Fraley

In this one, we're going to create a sample and I'm going to show you the document that we use to style or create our style sheets against. When you compose a document, a DITA document, it runs through the composition pipeline. The pipeline generates this intermediary document called a resolved document for styling, and that document contains all of the information from the map and topics. It kind of pushes some of the metadata down from the map into those topics and it generates links. So it's a little different than the document that you edit when you're creating content. But you want to use this as your starting point, the resolved document for styling for style sheet development.

[00:04:25.040] - Liz Fraley

So let's save this one here. This is going to be our sample starting document and we'll go to edit (menu) edit resolved document for styling. This is going to take all the content that you have in your map, all of the topics that are referenced and it's going to run it through the pipeline. And you'll see this document looks a lot like your content, but you'll notice there's a lot more data here.

[00:04:55.510] - Liz Fraley

It's a little intimidating at first, but what's important about this document is that it's the document that your style sheet is interacting with. You can also use it to troubleshoot any issues you have with linking as well. But I'll talk about that a bit later.

[00:05:10.430] - Liz Fraley

You'll notice that in my original document and let me bring this up side by side. You'll notice that I have this introduction to DITA and Arbortext and I have it here in the original. And you'll see that I have the DITA authoring overview chapter, it appears here and here with all the nested content embedded in it. So it's the same content, it's just now in the RDS document augmented with the additional metadata.

[00:05:46.560] - Liz Fraley

So just to talk a little bit more about the RDS document, this is a kind of hybrid DOCTYPE, if you will. It contains information from both the map and the topics. If you want to interact with this document, say, to go ahead and add additional cases or context for styling, we could save that off and we would do that by choosing enable editing. File, enable editing. We'll get a message, but don't be alarmed, this is just telling you that the context rules are off for this document. The reason for this is that it's a hybrid document that contains both map constructs and topic constructs. So the DTD for this does not really match all of the different cases that are here.

[00:06:29.790] - Liz Fraley

Now, I'm going to go ahead and save this off. Now, remember, this version is not really for editing. Just think of it as an intermediary document that you need for creating the stylesheet. The changes that you make to this document do not get saved back to your original topics. And that's really how this DOCTYPE differs from the resolved document for editing.

[00:06:59.230] - Liz Fraley

So just to touch on that for a moment, if you are an author and you wanted to work with all of the content in the map at one time, you could create this intermediary document called the resolved document for editing. Arbortext will create a valid window with all of the content and the map, and you can make any edits that you like.

[00:07:18.820] - Liz Fraley

I'll go ahead and bring that up. This is a little bit off-topic, but I think it's an important distinction to make. In the resolved document for editing, it contains all of your content. You can do global spell check or find and place, you can edit in this view if you prefer, and if you do make a change, it will allow you to go ahead and save that back to the file. That's the biggest distinction. The resolved document for editing creates an intermediary XML file that contains all the content from your map, it allows you to edit that content and then save that content back to those topic files. And you can see the handy dotted line that shows you where the boundaries for that file are.

[00:08:05.960] - Liz Fraley

Ok, the resolved document for styling is different in that it runs this content through the pipeline, it propagates the metadata from the map into the topic. It creates all of those different links, the hierarchical links, the parent-child links, any links you have in a relationship table, it creates those at that time. And then it creates this document here that propagation of metadata and the creation of links. That information is not stored back to your topics.

[00:08:42.130] - Liz Fraley

So let's move back to stylesheet creation. Now we have this document we can use as our starting point for stylesheet creation. The best way to get started for any stylesheet developer and it doesn't matter if you're making a couple of changes to the out of the box stylesheet. You don't ever want to change that content. The best way to get started is to come up here to the Styler menu and do New Empty stylesheet.

[00:09:08.960] - Liz Fraley

By doing this, we create what we call a driver file or shell stylesheet, we'll call this our demo stylesheet, and we'll give it a description, and we're just going to go ahead and select the defaults. You can always go back and change these at a later time. I can show you how to do that. So we're going to go ahead and choose, OK. And now we have this new empty stylesheet.

[00:09:37.730] - Liz Fraley

So let's go ahead and save that.  And we're going to save it into this demo directory that I have here. Notice it's a doc style and that's the extension we use for all of our styler stylesheets. We'll go ahead and hit save, but now we have an empty stylesheet that has no content. And what we recommend that you do, is that you pull in the out of the box stylesheet as a read-only stylesheet, as a starting point for your customizations.

[00:10:14.630] - Liz Fraley

Out of the box, Arbortext provides very extensive stylesheet that supports all of the DITA elements and attributes. What we're going to do is override those out of the box defaults you don't want to change the out of the box stylesheet. What you do is you go over to your install directory. And I have editor installed in my Program files, PTC, Arbortext Dditor directory. And we'll go here into the application directory where there's a com.arbortext.dita. And in the doctypes directory, you'll see all of the doctypes that support authoring DITA content. We're going to go here to this ditabase directory, and we're going to copy the ditabase.stylesheet style into the demo directory. And I've already done that.

[00:11:15.730] - Liz Fraley

If you go to properties, you'll see that this is a read-only and you want to keep it that way. But what now we're going to do is we're going to create a modular stylesheet architecture.

[00:11:34.630] - Liz Fraley

I'm going to add the ditabase to my stylesheet. File, modules, add, and here in the demo directory, we're going to add the read-only ditabase stylesheet.

[00:11:52.220] - Liz Fraley

Now, you'll notice how you've got a hierarchy. I'll show you a more complex hierarchy toward the end of our demo. But what we're going to do for this case is we're going to show you how to work with a read-only stylesheet and this flattened version of the modular stylesheet that we use for development. Just for simplicity, we'll start here. As soon as we hit close, it brings in all of those style definitions that were in the ditabase.style by hovering over this module here, we can see that it's read-only and that it's located in my demo folder. It's an easy way to see this information. Once you start working with a more modular stylesheet with one or two or more modules. It's extremely helpful to see where that information actually resides.

[00:12:37.770] - Liz Fraley

You'll notice that everything is light gray, that's because it's read-only. The reason for this, and the reason I'm emphasizing the read-only stylesheet is that the best practice for any development, be it DOCTYPE or Stylesheet or whatever, is always to create a copy for one provided out of the box to put it into a custom directory and make your modifications there. In this case, we want to be able to leverage any updates that Arbortext provides in the future, any updates, and product release. And by not altering the base stylesheet, I'll be able to just pop in a new one and not worry about migrating my changes over to that new base stylesheet. That's the important thing.

[00:13:19.490] - Liz Fraley

Now, what we want to do is this, we need to alter one or more of these elements, so let's take this one. We're just going to copy abstract we can either Ctrl C or right mouse button or use a menu item. We're going to copy it, we're going to paste and we get this message. Don't be alarmed, it's just telling you that pasting this element <abstract> will cause it to have higher precedence over the existing element <abstract>. And that's exactly what I want to do. This is an override, so I want it to have a higher priority or precedence than the element that's below it. You'll notice that when I pasted it, it gave me the option of renaming that element because I don't want to do that, I'll just go ahead and hit enter.

[00:14:05.960] - Liz Fraley

Now, you'll notice that this abstract element is bold and the other one is light gray and that it's also italicized. What also happened is that the precedents category changed from a solid block to this icon symbol here. And what this is telling you is that there is more than one element definition for abstract in this file. The Bold is telling you that this is the active element and the symbol is telling you the same thing. It's a blue box with the white box underneath for the active element and reversed for the overridden element, and if I hover over it, it will tell me this, it will say that this definition overrides another definition in a separate module. Or it'll tell me this definition is overridden by the definition in another module. It's a very handy way of seeing exactly what the status of our duplicate entries are. I can sort on this column as well. This is how you would go about overwriting Arbortext's out of the box styles for the DITA application. It's a very robust, very obvious, very powerful way of making minor modifications to meet the needs of your organization.

[00:15:21.560] - Liz Fraley

Now, PTC, re-did this styler UI in the 5.4 release and there are a lot of new things to talk about if you've used Styler in the past, this may look a little different.

[00:15:31.470] - Liz Fraley

Before I continue, Janice, do we have questions?

[00:15:37.260] - Janice Summers

If you have a question, please feel free to type it in the box. We'll give you a minute here. I don't have any questions in queue at the moment. So, again, feel free to type in questions if we don't get to them right now. We'll get to them in the next break, so Liz I guess if you want to carry on.

[00:15:57.010] - Liz Fraley

OK, so the next thing I want to touch on is the whole notion of fall-back generalization. In DITA, you always hear about specializations, a lot of people don't really understand what that means. But what it really is intended to do is to allow for this fall-back processing of information. All new elements are created based on an existing one.

[00:16:22.350] - Liz Fraley

The best example I can think of is an unordered list. So say you wanted to tailor your DOCTYPE and create a tools list. You'll create that tools list based on an unordered list. And it's very likely that the tool list will look exactly like an unordered list in your printed output. Well, in the past, when you were doing stylesheets, you'd have to single style every single element, regardless of whether it looked like any other element. So you'd have to style unordered list, you'd have to style your tool list and every other list construct. With DITA, because we know what the base element is, we can fall back. And if you don't style the tool list, it will fall back and it will be styled just like our unordered list. And the reason I'm making an issue of that or bringing that out is that there are a number of elements in our out of the box stylesheet that are unstyled by design. Let me go ahead and show you what I mean. So let's sort by style category and we'll go down to the bottom, I'm just going to hit Ctrl-END and you'll see that there are a lot of unstyled elements here. This is a little bit bigger, you'll see there's a lot of unstyled elements and you're thinking, oh, gosh, I never finished the stylesheet.

[00:17:37.240] - Liz Fraley

Well, no, they're unstyled by design. We want these elements to inherit the style from their base elements. Now, Styler proves by some hints to you, the stylesheet developer, about what's going on here. We can say that it's unstyled, it's a block by specialization, and if I hover over it, say this context here, we can see what it's specialized from. You'll see the tooltip that says this is a specialization of section using the formal block style. So if we went up, we could take a look at its parent and we would see how that style. It's very cool stuff.

[00:18:23.200] - Liz Fraley

It's difficult at times when you're editing to know what an element was specialized from, and I don't think that you really need to know in that case. But as a stylesheet developer, it is important that you know and especially important that you know what elements not to modify.

[00:18:39.310] - Liz Fraley

And if you'll look at this list, you'll see some of the main information types in DITA like concept and task and reference are not styled. They've been left unstyled. And you're probably wondering why wouldn't you style those elements? Well, this is a very important concept to understand when you're developing a chapter for a book, you can have a variety of concepts, task, and reference that make up that chapter. And the numbering is independent of what information type it is. So if the first section was a concept and the second section was a reference, the numbering should still be continuous to go one, two, three. What you don't want is to have your title element and that's where the numbering occurs for these different information types, you don't want it to be dependent on the type of information that you're working with.

[00:19:29.410] - Liz Fraley

Let me go ahead and show you real quick. First, I need to go up here and sort by element, and then real quick I hit a T and dropdown to title. And in title if I click the plus, I can see there are a number of constructs. Titles are used all over the place. Excuse me.

[00:19:56.140] - Liz Fraley

You'll see there's a title and topic, a chapter, a figure, a table, a map and once you start to nest these topics, you'll see the rules for that. That's when you have a title and a topic within a topic, within a topic. The numbering changes and it may have a different font family and it may have the size, either the size of the title is smaller or in a different color, or it's different because it's part of your chunk HTML output.

[00:20:21.490] - Liz Fraley

Well, if you intermingle all the task, concept, and reference, you would never be able to code all of the various combinations of those elements. It would be impossible. So what you want to do is develop your title context based on the base specialization, which is topic. So now it doesn't matter if it's a concept within a reference within a task. It will find the rule, which would be, let's say this one here, it'll use that one for any combination you organize of the information types within your map, that one will work.

[00:20:55.830] - Liz Fraley

So what would happen? Let's say you forget and you style concepts task for reference? Well, what's going to happen is that you're going to look at your styled output, and all of a sudden you're going to notice. Wait a minute, this one section isn't numbered consistently with the surrounding content. And you're going to be scratching your head and wondering why, and hopefully you'll figure out, oh, that was a concept and everything else is a task and I styled the concept. But it's kind of a tough problem to figure out. Unless you've been there a couple of times, so please! PTC is going to add more commenting to their stylesheets and they're extending the capability for you to comment yours.

[00:21:34.760] - Liz Fraley

To the right-hand side here, let's make this full screen, there's a comment, there's a comment field. This comment column you see here was added in the 5.4 release, PTC is in the process of self-documenting their next stylesheet that they'll deliver. And they'll provide that type of information that will keep you from making mistakes.

[00:21:56.740] - Liz Fraley

It's really easy to add a comment down here in the comment block. I can add a changed comment down in here and then it would show. Unfortunately, I picked an overridden comment, overridden element so I can't type in there because it's read-only stylesheet. But abstract, I have the override. And it appears right here in the comments, so please comment your stylesheets, make sure that you're documenting what you're doing so that anyone doing development can follow what you what you've done. It helps keep away those mistakes a lot really easy.

[00:22:38.920] - Liz Fraley

And Styler provides all these kinds of things, little tips that provide you with what you need to know as a stylesheet developer, it tells you, it gives you those hints. And basically, this is all you need to know that's different about a DITA Stylesheet from other stylesheets. There's a notion of fall-back processing and you want to take advantage of that to your best ability to make sure that you're not doing a lot of unnecessary styling. You want to make sure that when you style a specialization that you're not going to break anything like a numbering scheme or something to that effect.

[00:23:11.690] - Liz Fraley

Just think it through. It's something you wouldn't have to worry about, say, if you were working in Docbook. There's additional information available for DITA stylesheets that tells you whether it's unstyled, and what specialization, what is the specialization of, and to give you those additional hints, it makes it a lot easier to understand.

[00:23:31.260] - Liz Fraley

One of the complaints we hear about most frequently with DITA open toolkit, it's a great tool, but it's really hard to configure and require somebody with programming skills, somebody that really understands the DTDs. And what's nice about Styler product is that it's a tool that can be used by a non-programmer. It's very easy to understand. It provides you with the kind of information that you otherwise have to dig through a doc log file, one of the DTD modules to find. And we're trying to make it so that anyone, whether you're a person that's wearing multiple hats, you're the author and the stylesheet developer, or whether a dedicated stylesheet developer, it's a tool that just anyone can pick up and use.

[00:24:10.460] - Liz Fraley

So since we don't have a lot of time today, I want to switch it over and show you our best practice for doing stylesheet development. But before I do, Janice, do we have any more questions?

[00:24:19.790] - Janice Summers

I'm glad you asked. Yes, I do have a question. Can you add a general comment for the entire stylesheet, for example, versioning info?

[00:24:29.900] - Liz Fraley

So, usually that is not included in the stylesheet that would be included in Arbortext solution that's in your content management revision, control history. It would not be in the stylesheet itself. You can, push that in and out, but you wouldn't do that to the UI necessarily if you want that to be automated. Go ahead.

[00:24:53.320] - Janice Summers

  1. All right. Yeah, I have another question. Can Styler easily configure styles that will control XSL-FO, pagination, sidebars, footers, etc for PDFs?

[00:25:08.000] - Liz Fraley

So Styler does support XSL-FO rendering engine, and has one that it supports, and I showed that in the very beginning, but I can show that here again. Let's look at the stylesheet properties. My print PDF options, I can use the APP engine, I can use FOSI, I can use XSL-FO. Right now by default, it's set to FOSI, but later on I'm going to want to have it be APP, so let's add that. Whether how you write your, this is for developing XSL stylesheets. If you want it to run an XSL-FO stylesheet, you have to compose that in an XSL-FO editing tool. This doesn't export XSL-FO. But I could run an FO through its rendering engine. Does that answer the question?

[00:25:56.100] - Janice Summers

Yes, thank you. OK, if you have any other questions, go ahead and type them in. I see no other questions at the time so we can go ahead and carry on.

[00:26:08.430] - Liz Fraley

OK, good. Glad, I switched that APP now because I do want to come back to that later. All right. So the first thing I showed you was creating the Shell DTD and adding the flattened stylesheet from the Arbortext install stream. So and I guess I should step back and explain what I mean by flattened. If you go to the install tree in the Arbortext up to the directory. Let me go back to that.

[00:26:34.110] - Liz Fraley

In the Arbortext install tree for the DITA directory, there's a styler modules directory. PTC provides two types of stylesheets and we do as well, when we develop our stylesheets internally and for customers. We use a very modular stylesheet architecture. Those modules are located here in the stylers modules directory. It's a little intimidating, there are 31 modules, but these are all modules based on the way the language reference for DITA is organized. You'll see that you have your typographic domain elements, you have your topic elements, your task elements, table elements.

[00:27:15.980] - Liz Fraley

The reason why Arbortext created so many modules is that they figured that if you were going to specialize your typographic domain, you could just copy this with the module here and get started with your specializations. What they've heard is that people don't really understand all the modules, so they're planning on simplifying this. But you can create as many modules as you want after the fact. What we suggest people do when they're doing development is to use this modular stylesheet architecture. So how would you do that?

[00:27:45.220] - Liz Fraley

Well, let's go ahead and close the stylesheet that we had previously. Well, starting at the same starting point, we're going to go to Styler, we're going to create a new empty stylesheet and it's asking me if I want to save the other one. I'm going to say yes. So now we'll call this the modular stylesheet. Let me give it a quick description, and again, choosing the default and again, what we've brought up is what we call a shell or driver stylesheet, it's empty at this point.

[00:28:26.400] - Liz Fraley

And what I did earlier, is I came over to this directory and I copied all the modules into my new directory. We're going to go back to our stylesheet and we're going to go back to our file modules, and this time what we'll do is we'll add the main module file. File, modules, add, in the style modules, the main module file is, of the 31 files, the main one is this top file called the dita.style. And that's what pulls in all of the other modules. So you don't have to worry about adding all 31 once you add the main data style, as you'll see here in a second. What it'll do is it'll go through and validate and add all of these modules.

[00:29:22.970] - Liz Fraley

So it may seem a little slow, but it is validating all 31 modules, it's doing a lot of work here and here we have again the hierarchy of modules. It's a really large hierarchy, all 31 of the modules are here now. And what's nice about it is that you can add or remove modules you don't want. So, for example, this module here, the common topic elements for Styler pulls in all of these other files separately, if I didn't want the programming domain, it's one that's frequently removed, if I want to stylesheet, simplify the stylesheet, because I don't use it in my organization. I can just remove that whole programming domain and it would go away.

[00:30:10.580] - Liz Fraley

When I hit close, the Styler panel is populated with all of the elements. Now, I went through and I change these from read-only to write so I could make some changes. So you'll notice that everything here is bold. I would recommend, again keep a read-only copy of the modules. What's nice about working with the modular architecture is that now you can sort by module. So if I were working with the task element, and I wanted to see I could sort by task, and that everything related to the task is all nicely organized.

[00:30:43.780] - Liz Fraley

I don't have to jump around in my stylesheet, like when you're working with your typographic elements. Here they are, we've got bold, italics, superscript, subscript, so it's a very nice way of seeing them. Because when you're styling, you're typically styling a group of elements that are all related to a particular construct, and maybe they're all related to the glossary or related to the related links, that kind of thing. It makes it very easy to organize your work this way. But the real benefit of the modular stylesheet architecture is that once you've created this module, you can reuse it in your other stylesheets. You can very quickly develop one or more stylesheet just from leveraging these modules. A lot of our customers are doing page set this way. They're creating a module and putting all of the page set information in the module and then they create another stylesheet that pulls that module in. It adds a lot of flexibility to the stylesheet design and reduces the development time. It's much like a developer of an application would develop their code. They wouldn't put it all in one file.

[00:31:52.670] - Liz Fraley

OK, just a couple more things. You can move elements into another module, you can copy and paste these definitions and they add up. As you copy and paste, they end up here in the style driver file. Right, when we copied before we had the bold, abstract and the italics one and one was in the base and one was in our driver file this top-level stylesheet. So as you copy and paste and they end up in here, you might want to move them into another module. And you can do that right up here on the toolbar. I can move any object into a new module, I can pick it up and put it somewhere so I can pick it up and use it somewhere else. It makes it very easy to create these stylesheets. I've been to customer sites where they would have, say, five stylesheets and the copy changes from one stylesheet to another to the next, and it becomes a maintenance nightmare.

[00:32:45.470] - Liz Fraley

The best practice here is to use modules, have a single definition and then override, if necessary, that style in an alternate stylesheet. And it's very clear that way. You can look here and see, oh, this is how it altered or modified it and how it's different from the base. Like I mentioned earlier, there's this notion of precedence, it's true not only in this UI but within the modules UI, you can go back here and you'll notice that they're in a very specific order. Excuse me.

[00:33:22.020] - Liz Fraley

If I had a duplicate element defined in one or more modules, whichever module appeared first would take precedence over the one defined in the following module. So the hierarchy is very important when you're working with modules as well as this a lot.

[00:33:36.130] - Liz Fraley

Before I continue, Janice, do we have any new questions?

[00:33:41.780] - Janice Summers

None at this time.

[00:33:44.330] - Liz Fraley

OK, then we will continue on.

[00:33:52.760] - Liz Fraley

So working with specialized elements and relying on the fall-back processing is really the strength of DITA, and then you need to make sure that you understand it and that you leverage it. The Arbortext styler product really provides a nice tool for working with these doctypes. It's really appealing to non-programmers and to people who want to get up running fairly quickly.

[00:34:14.140] - Liz Fraley

My last point then would be that a lot of people don't realize that this is one stylesheet and from this one stylesheet, I can create multiple outputs. It's what we call a multi-channel stylesheet. You can go to print, you can go to PDF, HTML, create a web deliverable all from this one stylesheet, and it allows me to tailor if needed. The different constructs. Say, I wanted a different color font for HTML.

[00:34:41.150] - Liz Fraley

So let's try an example and let's say that we want to make our footnotes different in HTML we sort by element, we'll go up to footnote and we'll take a look at all the constructs that are available for foot-note. Let me open it up also so we can see what all the contexts are for foot-note. And I'll select footnote with ID down here in this tab in the description, we can see that we've made changes to the footnote that make it different from the other elements in the different contexts. It's in line and we've tailored the foot-note for HTML based on the different output formats. For it, Arbortext helps center DMP by using font web for the editor, we have a different color, how you get the information is to go here to outputs to edit.

[00:35:41.920] - Liz Fraley

Let's scroll this up a little bit, make it easier to see, down here in outputs to edit. If you apply a style to a base, it applies to all the outputs, print HTML all of the outputs listed here, but I can tailor a particular change to just one of them. So let's go to HTML file.

[00:36:03.270] - Liz Fraley

You'll notice that it's red now to tell you, hey, you're tailoring this footnote for HTML only. We can make it, we can change the color and make it this pretty red color. But if we were to print this to PDF, it would still be black, the only output where this would appear red is HTML. So if you have content that looks very similar in the web output or you just quickly want to produce some HTML output to review the styler tool is a great way to create a single stylesheet that will produce multiple different outputs, and it provides the UI that lets you quickly tailor that output for any given deliverable. And then you would go back to your base outputs. And if I look at the print, I can see it is still black and we're not going to edit it, so we'll just go back to the base.

[00:36:53.910] - Liz Fraley

That was the last thing I really wanted to point out, it's a very, very powerful tool. People really enjoy using it. It helps balance all of the dimensions for stylesheet work. It does a nice job of simplifying that view, you can get in trouble a little bit if you don't forget to change back to base. But you just have to be aware.

[00:37:14.350] - Liz Fraley

Arbortext tries to make people aware by changing things to red, saying, hey, you're still in HTML, but if you want to go back and style something different, be sure to change that back to base.

[00:37:23.690] - Liz Fraley

And there's a fair amount of things that you can do here, like source edits. There's a little column over here, this orange box column that gives you a view when there is source edits in the stylesheet, people sometimes have to go out and create some complicated changes and Arbortext has provided a tool that indicates that things have source edits now.

[00:37:50.890] - Liz Fraley

There's a lot of improvements going on to help people understand what's going on in the stylesheet things that might not have been obvious in the past, you may have noticed there's this different icon and there's a couple of different ways to flag a person that say, hey, this is this has source edit, this little icon down here. For those of you who aren't aware, the source edit is a very powerful mechanism for going above and beyond what you can do in styler UI and it lets you tailor that output for a given output formatter. You can add scripts, you can do all kinds of really interesting things using source edits, of course with that comes the knowledge to do it and the complexity to maintain those changes. So again, a good plan is important.

[00:38:31.200] - Liz Fraley

For example, I'll go and add my boxing module, it has APP source edits and you'll be able to see what I mean. They mostly come in as property sets and I have to change, I changed the prints engine already to APP so that I can apply the property sets to specific elements and I can leverage APP as easily as I can any other rendering engine freestyler as well. APP is the Arbortext advanced print publisher. The tool formerly known as 3B2. APP is another heavy topic that we can talk about later.

[00:39:04.590] - Liz Fraley

So let's add that module. I can add and I've got it up here at the top, I've got a boxing module, shows all the different things I can do, and we're going to move that up to the top on the hierarchy because we really want it to have precedence and we close, and it's validating to make sure that everything in there is solid stylesheet and no garbage. And up here, we can go to the property sets, and what we'll see here is that a whole bunch of things got at it all of these have they say APP has source edits and changes to properties. That's the things down here in this window will have no effect. There's a lot more things here now to give you hints about what's happening and why and where it is and what it was for.

[00:39:50.050] - Liz Fraley

All right, so let's come back to the slides really quickly.

[00:39:58.560] - Liz Fraley

Just to sum up, we start off by selecting a test document that contains many different contexts that we need to style, we then created a resolved document for styling. And when we did that, we created this intermediary XML file that contained all the content from our map and topics because it had been published through the pipeline. It's been augmented with additional metadata. It contains all of these related links and we can show this a different day, it's a heavy topic. We know that it's a special DOCTYPE because it's a combination of map and topic elements. So you can save it but you know that anything you change in the RDS document will not affect the source topics or map. It's a separate standalone file. So anything you do at this point is specific to that file.

[00:40:41.680] - Liz Fraley

We then went to Styler, we talked about the importance of developing modular stylesheets, the starting points for those stylesheets is to go out and locate either the modules or the flattened stylesheet out in the install tree, copy over read-only version and add it to your empty stylesheet. Make sure that if you have multiple modules that the precedents or the priority order is correct. And once you've got all your content into this file, if it's read-only it's light gray, and you can copy those definitions and make changes to them and you'll see that with duplicate definitions, the one that's active is bold the one that's been overridden is light grey italic. And there are some icon indicators to tell you what the precedence is.

[00:41:20.950] - Liz Fraley

Be aware that a lot of elements are unstyled by design. There's information about what they were specialized from and please don't ever, ever, ever style concept, task or reference. It'll monkey up your title memory and you don't want to do that.

[00:41:34.960] - Liz Fraley

That was pretty much everything we covered.

[00:41:38.260] - Liz Fraley

So before we get to the questions, here's a little bit about us and about PTC, and I wanted to take the opportunity to remind everyone about all of the resources available to the Arbortext community. Ours is a large and very tight-knit community, over the years, things have changed and particularly after the PTC acquisition, we found that a lot of people don't know all the resources available to them as Arbortext users. I've got a chart here, and this is from the list that we maintain here at Single-Sourcing Solutions. The URL for this is, the full list is down at the bottom of the page please this is really only a partial list of all the available things. If you want the full list then just be able to click on the links in these resources, use the URL at the bottom.

[00:42:21.280] - Liz Fraley

Janice, do we have questions?

[00:42:24.040] - Janice Summers

Yes, ma'am, we do. So one question, you may have already covered this but I'm going to go ahead and ask it, how do I compose to different channels using the same stylesheet, for example, in editor when composing on a PE server.

[00:42:40.430] - Liz Fraley

So let me show that briefly, it's really very simple, my output formats are right here, I can see what it looks like in the editor, I can see what it will look like in print preview, I can do PDF, HTML, Web preview, RTF, DMP, I don't have DMP installed but the, I can do it right from here.

[00:43:02.790] - Janice Summers

OK, does Styler allow you to preview the source edits?

[00:43:10.660] - Liz Fraley

So source edits are kind of a tricky thing, APP is not, which is what I have here, it's not an easy thing to look at, mostly I'll do APP start and most people will do APP source edits in a clips. There's a whole library and things to do that with, and you don't usually do that. When you step out of Styler, which is what a source edit is, you're stepping out for a reason and you're using some pretty heavy programming tactics and libraries to help you.

[00:43:41.920] - Janice Summers

  1. Back to the other question that you just answered. A follow-up question on that one was, are those shown in editor, too?

[00:43:53.020] - Liz Fraley

So in the editor view, let's come over to the actual sample. I would do file, compose, for web, print, HTML, PDF, HTML Hub, Digital Media Publisher that's it.

[00:44:10.930] - Janice Summers

OK, great that answered that question. OK, if you have a question, please feel free to type it into the question box. I think you had everybody's rapt attention. You provide a lot of great information in that presentation.

[00:44:38.720] - Liz Fraley

It's great. So I would say one more thing, maybe about when you choose the modular versus the flattened stylesheet and why we flatten it.

[00:44:48.660] - Liz Fraley

We develop with the modular stylesheet architecture. But when we roll it out to the field, we flatten the stylesheet and we flatten it for a number of reasons. It's simpler to keep track of one file and it improves performance. So what we do is we flatten all of these files, there's a toolbar item in Styler for that. All you do is save or merge stylesheet, you flatten that copy, and that would be the copy you deploy out to the field. You do all your development here in the modular architecture and then deploy the flattened to merge stylesheet out on the field. So if you're deciding, like, do I start with the flattened or do I start with the modular, it kind of it can add up and be different, reasons and it kind of depends on what you're doing, how many specializations you have and what your goals are, and you can kind of go either way. It's pretty easy, all you do is just right there save as merged stylesheet.

[00:45:46.530] - Janice Summers

OK, I have a question and a comment, I'll go with a comment first, and the comment is excellent information about stylesheet architecture and great demo.

[00:45:57.180] - Liz Fraley

Thank you.

[00:45:57.590] - Janice Summers

So kudos. Good job. Another questions come in. Is it possible to link to the out of the box stylesheet modules rather than copy them?

[00:46:07.540] - Liz Fraley

You could have yes, I wanted to monkey around with them, so I copied them to my custom directory. It's always a better idea to copy them off into somewhere else so that you're not depending on the install tree. It's just good practice. And if you're copying them over as read-only, it's not going to hurt you.

[00:46:34.110] - Janice Summers

  1. Any other questions?

[00:46:42.550] - Liz Fraley

I put my picture back up, the resources are huge.

[00:46:46.960] - Janice Summers

Yes, the resources is really important. Of course, they can always find it on our single Sourcing-Solutions website.

[00:46:54.350] - Liz Fraley

Absolutely.

[00:46:54.770] - Janice Summers

And while I'm waiting to see if any other questions are coming in, just to let everyone know we are recording this presentation it will be available to you. We have to do some code conversion on it before it gets posted. It usually takes me a day or two and you will all get your link to that as soon as it's up and ready for you to review. I have another comment that came in from one of the viewers today and saying, great presentation Liz.

[00:47:25.010] - Liz Fraley

Thank you.

[00:47:25.070] - Janice Summers

I have to agree.

[00:47:31.170] - Liz Fraley

Well, we've been using it for over a decade and doing this for much longer than that. And you know, our dedication to the community is such that we really want this information to be out there for you to have it, whether you're getting started or you've been a long time doing it and we hope everyone else exposes what they know to the community as well.

[00:47:55.120] - Janice Summers

So I have another question and I'm going to try and try my best to make sense of this question, so if I massacre it, I do apologize. So earlier you had touched on APP, and one of the questions is why would we want to use APP? The main advantages over FOSI or XSL-FO. Does that make sense?

[00:48:17.770] - Liz Fraley

It does it's not an easy question. APP is the advanced publishing engine, formerly known as 3B2. You can do, you only go to APP if you have to. Let's start there APP lets you create pretty much any look and feel you want, whether it just is a competitor for InDesign and you can do it in an automated black-box fashion. So, for example, if I were the Canadian government and I'm publishing multilingual legislation, it's very important that my paragraphs line up. Paragraph 3 on the left in English has to be directly opposite paragraph 3 on the right in French. And if the English paragraph runs longer than the French paragraph, when I get to paragraph 4, they must again be side by side. And that can be difficult to do if you don't have something that can just bring that text in and auto flow it, which APP can do, and it can control all of those things without a lot of machination on your end. That's kind of one of the things that they want to do. It's far beyond just simple I need a pretty cover page. What APP can do.

[00:49:35.770] - Janice Summers

It can also handle wrapping around images.

[00:49:40.010] - Liz Fraley

Well true, you can spill text around the clipping path and a graphic you can do Ruby or you do the special formatting language for Japanese text, formal Japanese text. I can print 3 languages on a single line at the same time, and auto-flow it so that it's all aligned. APP is for really advanced typographic publishing requirements and when you have them, you know it and you need it.

[00:50:09.320] - Janice Summers

Great. Thank you. I have another question that's come in. How difficult is it to work with a DITA customization that is to incorporate a stylesheet, a custom element with a unique styling that has no fall-back style?

[00:50:26.810] - Liz Fraley

Then you would just create a rule for that element and style it appropriately. I mean it's not different, right? Does that answer the question?

[00:50:45.520] - Janice Summers

I believe so. Yes, it does. Yes.

[00:50:49.180] - Liz Fraley

Good.

[00:50:51.740] - Janice Summers

We're at just a couple of minutes at the top of the hour, do we have any other questions? Any other comments? OK.

[00:51:07.160] - Liz Fraley

All right, great. Thank you for your time.

[00:51:08.280] - Janice Summers

So this will conclude this session for DITA style in Arbortext. It's easy. I hope you were able to see how easy it is. Our next Web session coming up in September 23, look for that invitation coming to you and it is a discussion with a panel of experts on the true ROI of XML. So look for that in your e-mail coming soon. Thank you very much for attending. And as soon as the recording is ready, we'll be sending out an announcement to you.

[00:51:40.640] - Janice Summers

Have a great day.

View the Slides

Where to find the supporting material

Members of the Single-Sourcing Solutions Mastermind Group have access to the recording, slides, show notes, sample code, and transcripts on the members website.

Tweet Roundup

In case you missed attending the session live, the event had a live Twitter stream.

Read the tweets
SingleSourcing
Aug 31, 2010 at 9:51am
#Arbortext #DITA Webinar L.Fraley: Get your Arbortext resources here: http://social.single-sourcing.com
SingleSourcing
Aug 31, 2010 at 9:51am
Top 5 Arbortext Resources from Single-Sourcing Solutions, qualified value added reseller for PTC dynamic publishing products - Arbortext Mathcad Windchill http://top5.arbortextuser.org
SingleSourcing
Aug 31, 2010 at 11:01am
#Arbortext #DITA Webinar L.Fraley: A giant chart of resources available to the Arbortext community and this is just a small slice!
SingleSourcing
Aug 31, 2010 at 11:00am
#Arbortext #DITA Webinar L.Fraley: Please don't ever, ever, ever, style concept, task or reference. Rely on fall-back processing!
SingleSourcing
Aug 31, 2010 at 10:59am
#Arbortext #DITA Webinar L.Fraley: Icon indicators, color, weight, hints to give you what you need to develop stylesheets right in the UI
SingleSourcing
Aug 31, 2010 at 10:57am
#Arbortext #DITA Webinar L.Fraley: RDS is a separate stand-alone file that does not affect your source content
SingleSourcing
Aug 31, 2010 at 10:56am
#Arbortext #DITA Webinar L.Fraley: Use the Resolved Document for Styling to see your content after it's gone through publishing pipeline
SingleSourcing
Aug 31, 2010 at 10:55am
#Arbortext #DITA Webinar L.Fraley: Use a test document that contains many of the different contexts you need to style
SingleSourcing
Aug 31, 2010 at 10:54am
#Arbortext #DITA Webinar L.Fraley: Added APP code by adding a module and changing rendering engine to APP. Voila! Cool.
SingleSourcing
Aug 31, 2010 at 10:53am
#Arbortext #DITA Webinar L.Fraley: Source edit support--source edits are mechanism for going above and beyond, like including APP code!
SingleSourcing
Aug 31, 2010 at 10:52am
#Arbortext #DITA Webinar L.Fraley: Styler is a very powerful tool; people enjoy using it. It does a nice job of simplifying the view
SingleSourcing
Aug 31, 2010 at 10:51am
#Arbortext #DITA Webinar L.Fraley: easy to see that style applies only to one format or to all. Red to indicate you're changing a subset/one
SingleSourcing
Aug 31, 2010 at 10:50am
#Arbortext #DITA Webinar L.Fraley: Styler can have multiple output formats from one stylesheet--true multi-channel stylesheeting
SingleSourcing
Aug 31, 2010 at 10:49am
#Arbortext #DITA Webinar L.Fraley: easy to move rules into/between modules and see precedence of modules
SingleSourcing
Aug 31, 2010 at 10:48am
#Arbortext #DITA Webinar L.Fraley: lots of customers using pageset modules
SingleSourcing
Aug 31, 2010 at 10:47am
#Arbortext #DITA Webinar L.Fraley: Sort by module--it's a nice way to organize your work, and you can reuse modules in other stylesheets
SingleSourcing
Aug 31, 2010 at 10:46am
#Arbortext #DITA Webinar L.Fraley: You can sort by module, and work on all TASK-related parts at once, see everything together.
SingleSourcing
Aug 31, 2010 at 10:44am
#Arbortext #DITA Webinar L.Fraley: Styler validates modules on import to make sure you don't have garbage in your stylesheet
SingleSourcing
Aug 31, 2010 at 10:43am
#Arbortext #DITA Webinar L.Fraley: Use a modular architecture to do your work, deploy flattened stylesheet to field--faster in production
SingleSourcing
Aug 31, 2010 at 10:42am
#Arbortext #DITA Webinar L.Fraley: Arbortext provides 31 modules OOB, easy to drop domains you don't use
SingleSourcing
Aug 31, 2010 at 10:41am
#Arbortext #DITA Webinar L.Fraley: Use the flattened base or the modules provided OOB to start your stylesheet work
SingleSourcing
Aug 31, 2010 at 10:40am
#Arbortext #DITA Webinar L.Fraley: Styler is a tool that just anyone can pick up and use
SingleSourcing
Aug 31, 2010 at 10:39am
#Arbortext #DITA Webinar L.Fraley: Styler is a tool that can be used by the non-programmer; easy to understand, with info/hints right there
SingleSourcing
Aug 31, 2010 at 10:38am
#Arbortext #DITA Webinar L.Fraley: OTK--a great tool, but takes programming skills, really need to understand the DTD to dig around in it
SingleSourcing
Aug 31, 2010 at 10:36am
#Arbortext #DITA Webinar L.Fraley: Make sure w/specializations, you're not going to break anything. Just think it through
SingleSourcing
Aug 31, 2010 at 10:35am
#Arbortext #DITA Webinar L.Fraley: There's a notion of fall-back processing and you want to take advantage of it: no unnecessary styling
SingleSourcing
Aug 31, 2010 at 10:34am
#Arbortext #DITA Webinar L.Fraley: Styler has all of these little tips that provide you w/what you need to know as a stylesheet developer
SingleSourcing
Aug 31, 2010 at 10:33am
#Arbortext #DITA Webinar L.Fraley: Comment feature added in 5.4, you can see/add comments easily, right in UI
SingleSourcing
Aug 31, 2010 at 10:32am
#Arbortext #DITA Webinar L.Fraley: Can sort by element and can quickly jump to rules, elements, and contexts
SingleSourcing
Aug 31, 2010 at 10:31am
#Arbortext #DITA Webinar L.Fraley: Styler provides hints--"this elt is a specialization of..."--stylesheet devs need this info at hand
SingleSourcing
Aug 31, 2010 at 10:30am
#Arbortext #DITA Webinar L.Fraley: Lots of elements in OOB stylesheets are "unstyled by design"
SingleSourcing
Aug 31, 2010 at 10:29am
#Arbortext #DITA Webinar L.Fraley: With DITA, take advantage of fall-back processing. Styler makes this easy to see.
SingleSourcing
Aug 31, 2010 at 10:27am
#Arbortext #DITA Webinar L.Fraley: For folks who used Styler in the past, it looks a lot different; lots of new things to talk about
SingleSourcing
Aug 31, 2010 at 10:26am
#Arbortext #DITA Webinar L.Fraley: Styler provides a very robust, obvious, powerful way to make modifications to meet org needs
SingleSourcing
Aug 31, 2010 at 10:25am
#Arbortext #DITA Webinar L.Fraley: Can sort on column to see active vs overridden rules.
SingleSourcing
Aug 31, 2010 at 10:24am
#Arbortext #DITA Webinar L.Fraley: bold=active rule; gray/italic=overridden rule. Easy to see.
SingleSourcing
Aug 31, 2010 at 10:23am
#Arbortext #DITA Webinar L.Fraley: Icon shows precedence and priority status of rules in stylesheet.
SingleSourcing
Aug 31, 2010 at 10:21am
#Arbortext #DITA Webinar L.Fraley: Knowing specialization history is important for stylesheet writers, pop up hint in Styler is handy view
SingleSourcing
Aug 31, 2010 at 10:20am
#Arbortext #DITA Webinar L.Fraley: Hover over element and you can see where it comes from (file, module) and what it's specialized from
SingleSourcing
Aug 31, 2010 at 10:19am
#Arbortext #DITA Webinar L.Fraley: by importing a read-only copy, you can leverage future updates provided by Arbortext
SingleSourcing
Aug 31, 2010 at 10:18am
#Arbortext #DITA Webinar L.Fraley: ATX provides a very extensive stylesheet that supports all of the DITA elements and attributes OOB
SingleSourcing
Aug 31, 2010 at 10:17am
#Arbortext #DITA Webinar L.Fraley: Start with an empty shell (driver) stylesheet and import read-only copy of OOB stylesheet
SingleSourcing
Aug 31, 2010 at 10:16am
#Arbortext #DITA Webinar L.Fraley: also an RDE - resolved document for editing - to see total -- editiable-- content in one view
SingleSourcing
Aug 31, 2010 at 10:15am
#Arbortext #DITA Webinar L.Fraley: RDS good for troubleshooting link problems, it's what's gone through the publishing pipeline
SingleSourcing
Aug 31, 2010 at 10:14am
#Arbortext #DITA Webinar L.Fraley: Styler has a "Resolved Document for Styling" (RDS) that contains all the info from map & topics
SingleSourcing
Aug 31, 2010 at 10:13am
#Arbortext #DITA Webinar L.Fraley: Style against a sample document that represents the vast majority of constructs you would see in output
SingleSourcing
Aug 31, 2010 at 10:12am
#Arbortext #DITA Webinar L.Fraley: Stylesheet creates the rules for how elements appear in the various contexts in the output
SingleSourcing
Aug 31, 2010 at 10:11am
#Arbortext #DITA Webinar L.Fraley: a single Styler stylesheet can create output for multiple output formats
SingleSourcing
Aug 31, 2010 at 10:10am
#Arbortext #DITA Webinar L.Fraley: Best practices for using Styler with the OOB DITA modular stylesheets
SingleSourcing
Aug 31, 2010 at 10:09am
#Arbortext #DITA Webinar L.Fraley: Talking about Styler - a UI to make non-programmers capable of maintaining/creating stylesheets
SingleSourcing
Aug 31, 2010 at 10:07am
#Arbortext #DITA Webinar L.Fraley: PTC pushing for interoperability, cooperation between applications -- based on customer feedback
SingleSourcing
Aug 31, 2010 at 10:06am
#Arbortext #DITA Webinar L.Fraley: Arbortext is the only OOB end-to-end solution with integrated products that all play nicely w/each other
SingleSourcing
Aug 31, 2010 at 10:05am
#Arbortext #DITA Webinar L.Fraley: Arbortext was Editor IBM was using when they developed DITA; Arbortext part of OASIS DITA TC from start
SingleSourcing
Aug 31, 2010 at 10:04am
#Arbortext #DITA Webinar L.Fraley: Arbortext has a long history with SGML, XML, and DITA. Around since 1990
SingleSourcing
Aug 31, 2010 at 9:57am
#Arbortext #DITA Webinar: about to get started...
SingleSourcing
Aug 31, 2010 at 9:57am
#Arbortext #DITA Webinar: We'll be live-tweeting the webinar. Fair warning: we're going into high-volume for the next hour.

Key concepts

arbortext styler, best practices, dita, stylesheets, techcomm tools

Filed under

Arbortext Monster Garage, Season 1, Webinars

%d bloggers like this: