Exercise 10: Single sourcing and content references

In this exercise, you'll apply conditional processing values and create content references. To do so, you will use the topics and maps that you created in Exercises 6, 7, 8, and 9.

The goal of this exercise is to learn how to:

  • apply conditional processing metadata to maps
  • apply conditional processing metadata to elements within topics
  • process output when using conditional values
  • create content references

Ensure that you read chapter 8, 9, and 10 of the DITA Best Practices book.

Step 1: Create the metadata values that you want to apply

To use conditional processing metadata, you must define the appropriate values within oXygen.

  1. Select DITA > Profiling / Conditional Text > Configure Profiling Condition Sets.
  2. In the Preferences window, select the row that says DITA* props and click Edit.
  3. In the Profiling Attribute window, click New.
  4. In the Add window, enter recipe1 in the Value field and click OK.
  5. Repeat steps 3 and 4 to create entries for recipe2 and recipe3.
  6. Ensure that Multiple values separate by <space> is selected and click OK.
  7. On the Preferences window, ensure that Project Options is selected and click OK.

Step 2: Add conditional processing attributes to your map

You now need to apply the conditional processing attributes to your map. For this example, add the props values that you added for recipe1, recipe2, and recipe3 to the corresponding task and reference <topicref> elements.

  1. Open your DITA map.
  2. Highlight the <topicref> element for the first recipe task.
  3. Select DITA > Profiling / Conditional Text > Edit Profiling Attributes.
  4. In The Editing Profiles Attribute window, select recipe1 in the Props section and click OK.
  5. Highlight the <topicref> for the corresponding reference topic for that recipe.
  6. Select DITA > Profiling / Conditional Text > Edit Profiling Attributes.
  7. In The Editing profiles window, select recipe1 in the Props section and click OK.
  8. Repeat steps 2 through 7 for the second and third recipes (and their corresponding reference toics) by using the recipe2 and recipe3 values for the Props attribute.

Step 3: Add conditional processing attributes to your topic

In this example, you are going to specify that the <prereq> elements have an audience value of novice so that the ingredient list is displayed only for novice readers.

  1. Open your first recipe topic.
  2. Position your cursor right behind the <prereq> starting element.
  3. Select DITA > Profiling / Conditional Text > Edit Profiling Attributes.
  4. In the Editing Profiles Attributes window, select novice under Audience and click OK.
  5. Repeat steps 1 through 4 for the other two recipe tasks.

Step 4: Create condition sets

In oXygen, you create a condition set to define which conditions you want to use when you transform your data. This method is the way that oXygen implemented the DITAVAL file that the book describes. In this exercise, you will create three conditions.

  1. Select DITA > Profiling / Conditional Text > Configure Profiling Condition Sets.
  2. At the Preferences window, create a condition that specifies to include recipes 2 and 3 in output.
    1. Under Profile Condition Sets, click New.
    2. Name your condition RecipesProps.
    3. Under the Props value, select recipe2 and recipe3.
    4. Click OK.
  3. Create a condition that specifies an expert audience.
    1. Under Profile Condition Sets, click New.
    2. Name your condition, ExpertAudience.
    3. Under the Audience value, select expert.
    4. Click OK.
  4. Create a condition that specifies recipe 1 and novice information.
    1. Under Profile Condition Sets, click New.
    2. Name your condition, NoviceRecipe.
    3. Under the Props value, select recipe1.
    4. Under the Audience value, select novice.
    5. Click OK.
  5. At the Preferences window, click OK.

Step 5: Publish your output using the conditions you specified

Test your conditional processing values by publishing using the different condition sets that you specified.

  1. Select DITA > Profiling / Conditional Text and select the RecipeProps condition from the menu.
  2. Publish DITA Map Webhelp output. The output should include recipes 2 and 3 – recipe 1 should be left out.
  3. Select DITA > Profiling / Conditional Text and select the ExpertAudience condition from the menu.
  4. Publish DITA Map Webhelp output. The output should include all three recipes; however, the <prereq> element and its contents should not be included in the recipe tasks. (Because you selected expert for audience, any element with an audience set to novice will be omitted from output.)
  5. Select DITA > Profiling / Conditional Text and select the NoviceRecipe condition from the menu.
  6. Publish DITA Map Webhelp output. The output should include recipe 1; recipe 1 should include the prereq section.
  7. Verify all conditions work correctly.

Step 6: Creating a content reference

You can create content in one file and share that content within other topics via a content reference. Good uses for this feature include product names or book titles, information that is likely to change, and information that you want to keep consistent in multiple topics. If you change the information in the file in which the content is stored, all the topics that reference that information will update to include the revised text.

  1. Identify a phrase or word that occurs in more than one of your files (for example, if some of your recipes include a common ingredient or if you have some common wording in one of your steps).
  2. Create the shared text:
    1. Create a new concept topic and name it sharedContent.dita.
    2. Provide a title and short description for the shared content file to indicate that the topic is used to contain shared content.
    3. In the body of the concept, insert a <p> element.
    4. Within the paragraph element, insert a <ph> element.
    5. Type the text that appears in multiple places within the <ph> element.
    6. Add an ID attribute to the <ph> element.
    7. Save your file.
  3. Reference the shared text in other topics:
    1. In your reference or task topic, delete the text where it originally occurred.
    2. Select DITA > Insert Content Reference.
    3. In the Insert Content Reference window, click the folder next to URL, navigate to your concept topic, and click OK.
    4. In the Target ID list, select the <ph> element that contains the commonly used word or phrase.
    5. Click OK to insert the shared word or phrase.
  4. Repeat steps 2 and 3 to add two additional words or phrases. (The concept topic that you created can include all of your phrases. Just ensure each phrase is included in a <ph> element and that you assign a unique ID to that phrase.)

Step 7: Zip your files and turn them in

Include the following updated files in a ZIP file ("yourName-SingleSource.zip") and upload it to BlackBoard:

  • concept topic from Assignment 6
  • 3 task topics from Assignment 6
  • 3 reference topics from Assignment 7
  • map file from Assignment 8
  • concept topic that contains the shared content

Note: You do not need to include output files within the zip file. I’ll generate output while evaluating the conditions.