1. Creating supertasks in DITA
Presented to the Silicon Valley DITA Interest Group
August 9, 2006
Megan Bock
All output samples use default IBM ID Workbench processing.
Other slides with speakers notes have an information icon in the lower right corner.
22 November 2018

2. Discussion topics What is a supertask? How do you create a supertask?
How do you add related content without interrupting the sequence?
What can you do to handle difficult supertasks?
22 November 2018

3. Supertask
A supertask is a series of tasks that the reader should perform in a specific order.
In DITA, a supertask provides automatic linking:
From the supertask to the step tasks
From each step task to the supertask
From each step task to the preceding and following step tasks
A supertask can be a step task in a larger supertask.
22 November 2018

4. Creating a supertask Create topics using the DITA task topic type:
Create a container topic for the supertask. Provide prerequisites, contextual information, and so forth.
Create a topic for each step task.
Add topic references in the DITA map:
Add a topicref element for the supertask container topic and set the collection-type attribute to sequence.
Insert the step topics. Nest them, in order, inside the container topic’s topicref element.
22 November 2018

5. A supertask in the DITA map
A step topic in a supertask can be the container for another supertask.
22 November 2018

6. The supertask container topic: DITA source and XHTML output
22 November 2018

7. Hierarchical links in output
XHTML: Hierarchical links are created in the supertask container at build time.
Numbered task links in the parent.
Parent topic links in each child.
Sequence links in each child.
PDF: No hierarchical links are created.
22 November 2018

8. The short description in hierarchical links
The title and short description become the ordered list items.
HTML output for task 1: <li class="olchildlink"> <a href="jack_assembling.html"> Assembling the jack</a><br /> Your jack might require assembly before you can use it to lift your vehicle.</li>
22 November 2018

9. Adding related content without interrupting the sequence
If you deliver PDF or books, insert a topicref element where you want to place the related content.
Use a relationship table to link to the related content from the supertask container and any of the step tasks.
If the related content is a child of the supertask container, turn off linking for the related content topic or topics.
22 November 2018

10. Inserting and linking a concept topic
← Use linking=“none” to keep the concept out of the task sequence.
← Use toc=“no” to keep the concept topic out of the navigation.
Use a relationship table to control all linking to the concept. →
↓ Use index entries normally.
22 November 2018

11. Using a relationship table to add a concept
Relationship tables define links outside the topic hierarchy.
Relationship tables can be designed in different ways. Basic designs include:
Source and target columns (shown)
Topic type columns
Single column
22 November 2018

12. The short description in related links
In XHTML output, the content of the shortdesc element becomes the title attribute on the related links, parent link, and sequence links. Sample output: <a href="jack.html" title="A jack is a device that you can use to lift a vehicle.">Jack</a>
In PDF output, the content of the shortdesc element is positioned below the related link.
22 November 2018

13. Difficult supertasks
A task in the sequence doesn’t have a topic or is not a local topic
Sequences intersect, fork, or run parallel
Intersecting: Two sequences use the same topic
Forking: The sequence splits and does not rejoin
Parallel: The sequence splits and then rejoins
22 November 2018

14. Solutions for difficult supertasks
Simulate a supertask
Slightly different output, especially in PDF
More difficult to maintain
Good for: step that is not a topic or a local topic
Use the copy-to attribute on a topicref element
More output files and longer PDFs
Duplicates in the index and search results
Good for: intersecting tasks
Insert a transition topic
Time-consuming to create and maintain
Good for: forking tasks
Create shell topics
Good for: parallel tasks, intersecting tasks
The simulated supertask is described in remaining slides.
The copy-to attribute creates a clone of the content as the specified file name in HTML output, or repeats the content in PDF. To use the copy-to attribute:
Insert a topicref element in the map.
Provide the source file as the href attribute.
Provide a new target name (that does not already exist) as the copy-to attribute.
A transition topic serves as the step in a supertask and uses its own child linking to manage the problematic linking.
A shell topic set stores the content in one topic, with an ID on the body element. Shell topics with their own titles, short descriptions, and index entries conref the body in.
22 November 2018

15. Tagging example for a simulated supertask
To simulate a supertask:
Make the short descriptions in the step task topics reusable.
Build the task as inline links in the steps of the supertask.
Break the generated linking in the map.
Rebuild the linking with a relationship table.
22 November 2018

16. Make the short descriptions reusable
Insert a ph element around the text of the short description. (You can’t reference a short description as the conref target in a step.)
22 November 2018

17. Build the tasks as steps
Create a step for each task topic.
Insert an xref element in the cmd element.
Insert an info element to hold the short description content.
Insert a ph element with a conref attribute targeting the topic’s short description.
22 November 2018

18. Break the generated linking in the map
Nest the step task topics inside the supertask container topic.
Do not assign a collection-type attribute on the topicref element for the supertask container topic.
Turn off linking to each of the step task topics in the supertask.
22 November 2018

19. Rebuild the linking with a relationship table
Duplicate the supertask structure in a cell in a relationship table.
For the supertask container topic, set the collection-type attribute to sequence and the linking attribute to target-only.
For each of the step task topics, set the linking attribute to normal. (The attribute is inherited from the supertask container, so you have to turn linking back on.)
22 November 2018

20. XHTML output comparison
Left: generated supertask. The paragraph “Review the instructions…” is a singleton step, followed by the three sub-steps.
Right: simulated supertask. In this version, the three former sub-steps become peers, increasing the number of steps and causing the first step to be numbered.
22 November 2018

21. PDF output comparison
Left: generated supertask. No links to the children are present in the PDF output.
Right: simulated supertask. Links are incorporated with short descriptions.
22 November 2018