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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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