Transcript Creating supertasks in DITA

Creating supertasks in DITA
Presented to the Silicon Valley DITA Interest Group
August 9, 2006
Megan Bock
20 July 2015
1
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?
20 July 2015
2
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.
20 July 2015
3
Creating a supertask
1. Create topics using the DITA task topic type:
a. Create a container topic for the supertask. Provide prerequisites,
contextual information, and so forth.
b. Create a topic for each step task.
2. Add topic references in the DITA map:
a. Add a topicref element for the supertask container topic and set the
collection-type attribute to sequence.
b. Insert the step topics. Nest them, in order, inside the container
topic’s topicref element.
20 July 2015
4
A supertask in the DITA map
A step topic in a supertask can
be the container for another
supertask.
20 July 2015
5
The supertask container topic: DITA source
and XHTML output
20 July 2015
6
Hierarchical links in output

XHTML: Hierarchical
links are created in the
supertask container at
build time.




20 July 2015
Numbered task links
in the parent.
Parent topic links in
each child.
Sequence links in
each child.
PDF: No hierarchical
links are created.
7
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>
20 July 2015
8
Adding related content without interrupting
the sequence
1.
2.
3.
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.
20 July 2015
9
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. →
↓
20 July 2015
Use index entries normally.
10
Using a relationship table to add a concept


20 July 2015
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
11
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>

20 July 2015
In PDF output, the
content of the
shortdesc element is
positioned below the
related link.
12
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
20 July 2015
13
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
20 July 2015
14
Tagging example for a simulated supertask
To simulate a supertask:
1. Make the short descriptions in the step task topics reusable.
2. Build the task as inline links in the steps of the supertask.
3. Break the generated linking in the map.
4. Rebuild the linking with a relationship table.
20 July 2015
15
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.)
20 July 2015
16
Build the tasks as steps
1. Create a step for
each task topic.
2. Insert an xref
element in the
cmd element.
3. Insert an info
element to hold
the short
description
content.
4. Insert a ph
element with a
conref attribute
targeting the
topic’s short
description.
20 July 2015
17
Break the generated linking in the map
1. Nest the step task topics
inside the supertask
container topic.
2. Do not assign a
collection-type attribute
on the topicref element
for the supertask
container topic.
3. Turn off linking to each
of the step task topics in
the supertask.
20 July 2015
18
Rebuild the linking with a relationship table
1. Duplicate the supertask structure in a cell in a relationship table.
2. For the supertask container topic, set the collection-type attribute to
sequence and the linking attribute to target-only.
3. 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.)
20 July 2015
19
XHTML output comparison
20 July 2015
20
PDF output comparison
20 July 2015
21