VideosDITA 1.3 (Key Scopes, Branch Filtering)

Table of Contents
  • Introduction00:43
  • Key Scopes07:13
  • Branch Filtering04:22

Overview

Duration: 12:18
This video presents two new features of DITA 1.3 (key scopes and branch filtering) that allow you to maximize the reuse possibilities for keys in topics and reuse the content of topics multiple times within the same map, each time using a different filter.

Transcript

00:00:07With the launch of version 17.1 oXygen introduced support for DITA 1.3.
00:00:13This demonstration will focus on two of the DITA 1.3 features, namely "keyscopes" and
00:00:20"branch filtering".
00:00:22The goal of this demonstration is to show how we can use some of the features of DITA
00:00:271.3 to reuse content as much as possible in order to produce a brochure for a line of
00:00:33products in our case two generic phone models, named X1000 and X2000.
00:00:44Each of these phones need a overview topic with a basic layout that contains a title,
00:00:50a product image and a short description.
00:00:53Translated into DITA, this might be a topic that uses variables for its title, image and
00:01:00content, allowing us to use it in the brochure for both phones.
00:01:06And this is where the DITA 1.3 keyscope concept can be helpful, allowing different key values
00:01:12to be supported at various locations within a map.
00:01:16So, in our example, we have a topic (called overview.dita) that is being reused in two
00:01:24places within a map and we specify different key values in each of the locations
00:01:30where the topic appears.
00:01:32Keyscopes help you to maximize the reuse possibilities for keys in topics and it is now possible
00:01:39to use one key in a topic that reflects different values depending on the defined scope of its location.
00:01:48First we need to make sure that the DITA 1.3 support is enabled.
00:01:53We go to the oXygen preferences, then to the DITA page and switch the DITA processing engine
00:01:59to the built-in DITA-OT 2.x since it supports DITA 1.3.
00:02:06Now we create a new DITA map file and open it in the DITA Maps Manager View,
00:02:15... then save it on disk.
00:02:20To change the map's name we'll use the newly enhanced Edit Properties dialog box.
00:02:32Next... we'll create the overview.dita topic that is meant to be an introductory page for
00:02:38both phones.
00:02:41We use a Topic template and store it in our "topics" folder.
00:02:56Since the content of this topic depends on the particular phone model, we'll define keys
00:03:01that contain the information for each of them.
00:03:04The first piece of information that is suitable to be kept as a key is the phone model.
00:03:09We create a key as the child of the phone overview topic...
00:03:13The key is called model and its value is X1000.
00:03:18Then we use the key in the topic title by using the revamped "Reuse Content" dialog box.
00:03:27Notice that we can now insert a key reference using the Choose key button.
00:03:46Now let's define the key that points to an image of the phone ...
00:03:51First we give the key a name, which is "image"... then we select the Target tab and browse for
00:03:57the actual image file.
00:04:05Notice that the key has been created and added to the map.
00:04:09The topic's layout is simple.
00:04:12It will contain an image with a short marketing message next to it, so we'll use a simple
00:04:18table... with no title ... one row and two columns.... no header... no frame ... no row or column separator.
00:04:32Now we use the Insert Image action to insert the image into our topic.
00:04:38Again... notice that we can use the Choose Key button to browse the available keys.
00:04:48Next... we create another key that holds a short description of the phone.
00:05:04...and insert it using the Reuse Content action.
00:05:18To align the description with the image, I'm going to adjust the table cell properties.
00:05:26Now we save the topic ... and then the map.
00:05:32For the other phone model, we want the brochure to have the same structure, so we'll reuse
00:05:37the overview.dita topic, but using different values for the three keys.
00:05:43This is where the DITA 1.3 key scopes can be useful ... so now we need to define them.
00:05:51For the X1000 phone overview topic we set the value of the keyscope as "X1000scope".
00:05:59Notice that the keyscope value is displayed in the DITA Maps Manager view in brackets.
00:06:04Now... we reference the topic again... this time for the X2000 phone model.
00:06:11So we'll set the value for its keyscope as "X2000scope".
00:06:22As we have seen, the topic uses keys that expand to specific content, so we need to
00:06:27define new keys for the X2000 phone model.
00:06:31Again...
00:06:32We define the "model" key but this time set it to X2000...
00:06:40then the "image" key to point to the correct image ...
00:06:59...and finally the "description" key.
00:07:11We save the map...
00:07:13Now you can see that when we open the same file, but in different scopes, the content
00:07:19is expanded properly.
00:07:21Also, when a file is referenced in multiple locations in the same map, there is a visual
00:07:26indicator in the top right-hand corner and the two arrows allow us to navigate between the references.
00:07:33Now let's see how the brochure looks after we transform it into a PDF using a default
00:07:38DITA Map to PDF transformation scenario.
00:07:43This was just a small example involving two phone models, but imagine how using key scopes
00:07:49can save a lot a time when you have a lot of content to reuse.
00:07:57In the second part of the demonstration we'll try to expand our brochure with more information,
00:08:03by reusing an existing DITA project with basic specifications for the two phone models.
00:08:09This project contains a DITA map that holds several topics and makes extensive use of
00:08:15profiling attributes.
00:08:17We see that the topics contain profiled information for both phone models.
00:08:22Notice that "product" is used as a profiling attribute.
00:08:26Each topic contains information that is common for both phone types and information tailored
00:08:31specifically for each model.
00:08:34Using DITA 1.2, you can apply only one DITAVAL filter to a map.
00:08:40This means that in the same publication you cannot merge the content that results after
00:08:45applying distinct profiling conditions on the same source.
00:08:49However, the DITA 1.3 "branch filtering" mechanism makes it possible to reuse the content of
00:08:55topics multiple times within the same map, each time using different filters.
00:09:02In our use case, we'll generate a single publication that contains information about the two phone
00:09:08models by reusing the contents of individual topics multiple times within a single map,
00:09:15each time using different filtering conditions to produce different, tailored output.
00:09:23We add the "phoneDetails" map to our brochure map to include the information for the first
00:09:28phone, the X1000.
00:09:38However, we need to filter out the X2000-related information and keep only the X1000-related information.
00:09:47We'll do this by using the branch filtering mechanism, which requires a DITAVAL file to
00:09:52control the profiling conditions for each branch.
00:09:56We create a new DITAVAL file from an oXygen template file.
00:10:02We'll switch to the Author mode... we keep only one filter and we want to exclude the
00:10:09X2000 model.
00:10:23We save the file as "X1000only.ditaval".
00:10:29Now we can apply the filter to obtain the X1000 branch.
00:10:34Invoke the contextual menu on the map reference and append a DITAVAL reference as its child.
00:10:46At this point, the first branch will produce an output that contains only the X1000-related information.
00:10:53Similarly, we create the X2000 branch: add the map reference...
00:11:06create a ditaval file ... filter out the X1000 content...
00:11:26save the DITAVAL file...
00:11:31then reference it as a child odf the Map.
00:11:45Now it's time to see how the two references of the same map are filtered in the final output.
00:11:51We apply a default DITA Map to PDF transformation.... and notice that the output contains separate
00:11:57sections for both phones, all extracted from the same source map.
00:12:03Again, this was a simple example, but you can imagine how using the DITA 1.3 branch
00:12:09filtering mechanism can help you tailor your output starting from a single source.
00:12:14And this concludes our demonstration.
00:12:17Thank you for watching.

Use Oxygen Feedback to ask us anything about this video.

Products

Features

Shop

Resources

Support

Company

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

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