VideosDITA Subject Scheme

Overview

This video demonstration shows you the basics of using a DITA Subject Scheme Map to create and manage custom profiling values that allow you to filter content in Oxygen's Author mode or in transformed output.

Transcript

00:00:07The purpose of this video is to show you the basics of using a DITA Subject Scheme Map
00:00:11to profile content in Oxygen.
00:00:14A subject scheme map allows you to create and manage custom profiling values in DITA
00:00:19documents and it uses key definitions to define a collection of attribute values instead of
00:00:24a collection of topics.
00:00:26By defining controlled values and using hierarchical levels in the subject scheme map, you can
00:00:32filter and flag content in Author mode or in transformed output.
00:00:36The advantages of using a subject scheme to control profiling attribute values include:
00:00:43First:
00:00:44You can create a hierarchy of profiling attribute values and use a DITAVAL file to filter them
00:00:49Second:
00:00:51You can share the files with others without having to share preferences or the entire project.
00:00:56Third:
00:00:57The subject scheme offers validation support so you are notified if an undefined value
00:01:01is used
00:01:02For the purposes of this demonstration, I will focus on a use-case where I want to customize
00:01:07the values of the 'audience' profiling attribute.
00:01:10More specifically, I want the audience attribute to offer values that identify the various
00:01:16audience types for a gardening publication.
00:01:19I want my subject scheme to include two categories for the intended audience, 'expert' and 'novice',
00:01:26and the 'expert' category will have two subcategories, 'botanist' and 'gardener'.
00:01:32This will allow me to profile my content so that the output gets filtered to only include
00:01:37information relevant to each category of user.
00:01:41Now I'll show you how to create a subject scheme map in Oxygen using a built-in template.
00:01:46I will click the "New file" button on the toolbar to open a New Document Wizard.
00:01:51Now I'll search for the subject scheme template...
00:01:55I'll select the template, give it an appropriate name, and click "Create"...
00:02:04...and the subject scheme file is opened in the editor.
00:02:07To define my subject scheme I can either use the visual controls that you see here in Author
00:02:13mode ... or I can switch to Text mode and define it there.
00:02:17Both methods are pretty fast and simple so it's just a matter of preference.
00:02:22For this demonstration, I'll use the Author mode controls...
00:02:26Notice that the template includes navigation titles.
00:02:30These elements are not required but you can use them if you want to show an alternate
00:02:34name when selecting attribute values in Oxygen ... instead of seeing the actual value.
00:02:39For example, if you want to use an abbrieviation or code for defining the value but you want
00:02:45to show the full name shown in Oxygen.
00:02:47For my purposes, I'm going to delete those unnecessary elements since I want to use the
00:02:52actual values...
00:02:54Now I'll define the hierarchy for my subject scheme and assign values for the keys...
00:03:00This first value is for the key that represents the whole tree of values so I'll call it "audienceKey".
00:03:07Now, remember the values and structure that I want for my subject scheme...
00:03:15so, this next value will be "expert" ... then I need the two subcategories to be "botanist"
00:03:22and "gardener"
00:03:25now I need to create a new value for the "novice" category and I want it to be on the same level
00:03:30in the tree as the "expert" category ... so I'll click the appropriate plus sign button...
00:03:37and I'll enter "novice" for the value
00:03:41Next I need to bind my tree of values to the particular attribute ... So, the attribute
00:03:46is "audience"
00:03:47and I want to bind it to the key I used for the whole tree of values ... I called it "audienceKey"
00:03:55... I'll save the file...
00:03:58Notice that I have a validation error ... That's because I still need to add a reference to
00:04:04my subject scheme in my main DITA map.
00:04:07I'll do that now.
00:04:09The easiest way to do this is to keep the subject scheme file opened in the editor,
00:04:14then in the DITA Maps Manager, right-click the main map and select "Append Child", then
00:04:20"Reference to the currently edited file".
00:04:23This opens a dialog box where you can configure the reference however you want, but there
00:04:28is one specific thing that you need to do to define your reference as a subject scheme
00:04:33map for its type.
00:04:35To do this, go to the "Atributes" tab, and in the "Type" field, enter or select "subjectScheme".
00:04:43I'm also going to enter a Navigation title that will appear in the DITA Maps Manager.
00:04:48Now I click "Insert and close", I save my map, which binds my subject scheme to the
00:04:55main map ... and now I'll test my subject scheme.
00:05:00I'll right-click one of the topics in my map, go to "Edit Properties", and to the "Profiling" tab.
00:05:08Notice that Oxygen has merged the profiling attribute that I defined in the subject scheme
00:05:12map with the default attributes.
00:05:15These other profiling attributes are not relevant in my case, so ideally it would nice if they
00:05:21were not displayed at all.
00:05:23I'll show you how you can use the subject scheme file to overwrite or filter them out.
00:05:29In the binding section, I click the plus sign to add a new binding.
00:05:35I'll enter one of the attributes I want to filter out ... I'll leave the 2nd box blank
00:05:41and this will instruct Oxygen to reject all possible values for this attribute.
00:05:48I'll add the other attributes I want to overwrite...
00:06:00Now, after saving the subject scheme file, if I go back to the Profiling tab in the Edit
00:06:06Properties dialog box, you see that only the "audience" profiling attribute is available
00:06:11along with its values.
00:06:16To illustrate the advantages of using a subject scheme, I'll show you an example of each of
00:06:21them in action...
00:06:24The ability to create a hierarchy of controlled values makes profiling even more efficient.
00:06:30I've created a DITAVAL file that simply filters the "expert" value from the "audience" attribute.
00:06:42Now I'll create a condition set called "Novice only" that uses my DITAVAL file.
00:07:06Next, I'll open a topic that has content profiled for both "botanist" and "gardener".
00:07:14Now I want to see what it will look like if I exclude my expert values, so I'll select
00:07:20the condition set I just created ... and you see that it filtered out both values that
00:07:26were defined in my hierarchy.
00:07:30The next advantage is that if you want to share your custom profiling values with others
00:07:37you only need to share the files...without having to share your preferences or your entire project.
00:07:49The other advantage is validation support.
00:07:53I'll run a valdiation on the DITA Map ... you see that I have a validation error that tells
00:08:01me I have an undefined profiling value ... and I can easily correct this problem by deselecting
00:08:10that wrong value and selecting the correct one.
00:08:18Now I'll run the validation again...and you see that we no longer have the error.
00:08:26For more information on various other DITA profiling possibilities, see the Oxygen user
00:08:31manual or our other similar video demonstrations.
00:08:34This concludes the demonstration.
00:08:37Thank you for watching.