230 likes | 1.07k Views
Creating supertasks in DITA. Presented to the Silicon Valley DITA Interest Group August 9, 2006 Megan Bock. Discussion topics. What is a supertask? How do you create a supertask? How do you add related content without interrupting the sequence?
E N D
Creating supertasks in DITA Presented to the Silicon Valley DITA Interest Group August 9, 2006 Megan Bock
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?
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.
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.
A supertask in the DITA map A step topic in a supertask can be the container for another supertask.
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.
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>
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.
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.
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
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.
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
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 • Time-consuming to create and maintain • Good for: parallel tasks, intersecting tasks
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.
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.)
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.
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.
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.)