LavaCon 2017 - Reusing Your Reuse: How to Keep the Reuse You Have When You Move to DITA

Copyright © Stilo International plc, 2017.Copyright © Stilo International plc, 2017.
REUSING
YOUR REUSE:
How to keep the
reuse you have
when you move
to DITA
Helen St. Denis
Conversion Services Manager
Stilo International

Copyright © Stilo International plc, 2017.
► Works closely with Stilo Migrate customers,
helping to analyse their legacy content and
configure appropriate mapping rules
► Provides Migrate customer training and support
► Helen has helped Migrate customers to convert
tens of thousands of pages of content to DITA
and custom XML
► BA in English from St. Francis Xavier University in
Antigonish, Nova Scotia and has pursued
graduate studies at Queen’s University in Kingston
Ontario
Helen St. Denis | Conversion Services Manager

The three R’s of DITA

► Most authoring environments offer some form of
content reuse capability
► Yes, even Microsoft Word!
► Some do a very good job of it, too
► Do we have to lose all the work we’ve put into reuse
when we move to DITA, and start all over again?
But … haven’t I already got reuse?

► At the document level
► At the phrase level
► Somewhere in between
Legacy reuse at various levels

► Adobe FrameMaker has books …
► You can use the same chapter (.fm file) in many
books
► You can maintain a folder of shared chapters to
which a book can refer, or you can keep all the
chapters together with several maps
Reuse at the document level …

… reuse at the document level
► MadCap Flare and Adobe RoboHelp have one or
more ToCs to assemble the HTML files into a project

… reuse at the document level
► Microsoft Word has Master Documents
► Like a ToC, it assembles various DocX files into one
document
► Any of these DocX files could be used in more than
one master document
► They are assembled through linking

Reuse at the phrase level
► Word has auto text
► FrameMaker has variables
► RoboHelp and Flare also have variables

► FrameMaker has text insets
► Flare and RoboHelp have snippets
► Word is not much help here!
Reuse at the in-between level

Conditional text
► Not actually reuse, but facilitates it …

Bonus: Keywords, glossaries and index terms
► This isn’t reuse, exactly, but you’ve put effort into
generating these things and don’t want to lose them

So how does this all work in DITA?
► Reuse in DITA is at the element level
► Some of this will be straightforward,
but some will not

DITA reuse at the document level
► Maps can bring in other maps
► So you could create maps on a per-document basis,
and include the map in as many other maps as
needed
► In FrameMaker, this is often a map per chapter
► In Flare or RoboHelp, it might be a map per HTML
page, or a map per folder
► In Word, a map per Word document

► This might be conrefs, conkeyrefs, or keys
► Generally variables can be readily converted to keys,
conrefs or conkeyrefs
► Conref files or keys can be created from the legacy
content, or pointers to an existing reuse library can
be inserted
DITA reuse at the phrase level

<keydef keys="prodname">
<topicmeta>
<keywords>
<keyword>OmniMark</keyword>
</keywords>
</topicmeta>
</keydef>
<keydef keys="_component">
<topicmeta>
<keywords>
<keyword>OMCPE</keyword>
</keywords>
</topicmeta>
</keydef>
Keys

OmniMark Concurrent Processing Engine runs programs written
in the <keyword outputclass="ID-000001d9" keyref="Prodname">OmniMark</keyword> programming
language. 
<map>
<title/>
<keydef keys="Prodname">
<topicmeta>
<keywords>
<keyword>OmniMark</keyword>
</keywords>
</topicmeta> </keydef> <keydef keys="_component">
<topicmeta>
<keywords>
<keyword>OMCPE</keyword>
</keywords>
</topicmeta> </keydef>
In the topic, and in the map

DITA reuse at the in-between level
► DITA reuse at the element level
► Topic level is the most obvious way
► <topicref> in the map

Challenges with topicrefs
► Most legacy formats don’t have topic-level reuse
specifically
► Flare or RoboHelp HTML files might be a single
topic, but usually are not

Conrefs
► Conrefs allow you to reuse a single DITA element
► This means you can reuse a paragraph, a table, a single list item
or a whole list
► You can also reuse the content at a phrase level, so that the content
of a step in a task topic, for example, can be reused inside a list in a
concept

Conref range
► This allows you to reuse a chunk of content that
includes more than one element
► But, the first and last elements must be the same
► So, you can reuse a set of list items from a list using
conref range
► But, you can’t reuse a chunk that starts with a list item
and ends with a paragraph or a table

From our example:

We can reuse the list…
<ol id=change-warnings-list>
<li> to ignore the class of warnings, use <codeph>-warning-ignore
warning-class</codeph>,</li>
<li> to report only a summary of the class of warnings, use
<codeph>-warning-summary warning-class</codeph>,</li>
<li> to report the warning and continue compiling, use <codeph>-
warning-report warning-class</codeph>, and</li>
<li> to promote the class of warnings to an error, use <codeph>-
warning-error warning-class</codeph>.</li>
</ol>

In the topic
<ul conref="generalConref.xml#titles/change-warnings-list">
<li> to ignore the class of warnings, use <codeph>-warning-ignore
<li> to report only a summary of the class of warnings, use
<codeph>-warning-summary warning-class</codeph>,</li>
<li> to report the warning and continue compiling, use <codeph>-
warning-report warning-class</codeph>, and</li>
<li> to promote the class of warnings to an error, use <codeph>-
warning-error warning-class</codeph>.</li> </ul>

Or reuse just some of the bullets:
<li id="change-warnings-1"> to ignore the class of warnings, use
<codeph>-warning-ignore warning-class</codeph>,</li>
<li id="change-warnings-2"> to report only a summary of the class of
warnings, use <codeph>-warning-summary warning-class</codeph>,</li>
<li id="change-warnings-3"> to report the warning and continue
compiling, use <codeph>-warning-report warning-class</codeph>, and</li>
<li id="change-warnings-4"> to promote the class of warnings to an
error, use <codeph>-warning-error warning-class</codeph>. </li>
In the topic
<ul>
<li conref="generalConref.xml#titles/change-warnings-1"
conrefend="generalConref.xml#titles/change-warnings-3"/>
<li>Another, different list item</li>
</ul>

Challenges with conrefs
► Snippets and text insets can contain anything; any
number of different elements
► It is not possible, therefore, to make a conref from
each one
► Nor is it possible to make a topic from each one

Identifying the reused content
► Text insets and snippets are in their own file – we can
use the filename
► We can create conrefs using the filename as identifier
► Each block level element becomes a conref (and so
do inline elements, if you like) with the filename as ID
► Other schemes for creating IDs are possible

Text inset …

<li id="change-warnings"> to ignore the class of warnings,
use <codeph>-warning-ignore warning-class</codeph>,</li>
<li id="change-warnings-1"> to report only a summary of the
class of warnings, use <codeph>-warning-summary warning-
class</codeph>,</li>
<li id="change-warnings-2"> to report the warning and
continue compiling, use <codeph>-warning-report warning-
class</codeph>, and</li>
<li id="change-warnings-3"> to promote the class of warnings
to an error, use <codeph>-warning-error warning-
class</codeph>.</li>
You can also use the
<codeph>all</codeph> warning class to quickly apply the same
command-line option to all classes of warnings. For
example,
<codeblock id="change-warnings-5"> -warning-error all -
warning-ignore uninitialized-data-access</codeblock>
would report warnings for any
warning other than <codeph>uninitialized-data-
access</codeph>.
This is what it could look like …

… in an XML editor

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="titles">
<title>Reference definitions</title>
<conbody>
By default, the<keyword keyref="Prodname">OmniMark</keyword>
compiler will display all these classes of warnings except for uninitialized-data-access, which
is ignored. You can change how each class of warning is handled using the following command line
options:
<ol id=change-warnings-list>
<li> to ignore the class of warnings, use <codeph>-warning-ignore warning-
class</codeph>,</li>
<li> to report only a summary of the class of warnings, use <codeph>-warning-summary
<li> to report the warning and continue compiling, use <codeph>-warning-report warning-
class</codeph>, and</li>
<li> to promote the class of warnings to an error, use <codeph>-warning-error warning-
class</codeph>.</li>
</ol>
You can also use the <codeph>all</codeph> warning class to
quickly apply the same command-line option to all classes of warnings. For example,
<codeblock id="change-warnings-6"> -warning-error all -warning-ignore uninitialized-data-
access</codeblock>
would report warnings for any warning other than
<codeph>uninitialized-data-access</codeph>.
</conbody>
</concept>
… in the raw DITA

► DITA has built in profiling attributes
► Or you can use “otherprops”
Conditional text

<?xml version="1.0" encoding="UTF-8"?>
<val>
<prop action="include" att="otherprops"
val="port-locking"/>
</val><val>
<prop action=“exlude" att="otherprops"
val=“no-port-locking"/>
</val>
DITAVAL file

<topicref navtitle="Generating a license request
key (port locking)"
href="1.5.8_Generating_a_license_request_key__po
rt_locking_.dita" product="omspe
omdc"></topicref>
<topicref navtitle="Generating a license request
key"
href="1.5.8_Generating_a_license_request_key.dit
a" product="omcpe ombc"></topicref>
Using a profiling attribute

► A RoboHelp glossary is almost DITA already
<glossentry>
<glossterm>CSH</glossterm>
<glossdef>(Context Sensitive Help)</glossdef>
</glossentry>
<glossentry>
<glossterm>Opportunity</glossterm>
<glossdef>Any contact with a customer (or potential
customer) is generically known as an opportunity. This is
because you have an opportunity to convert a potential customer
to an actual customer. Or an opportunity to deepen and
strengthen the existing customer experience.</glossdef>
</glossentry>
Glossaries

Indexes

In the DITA

LavaCon 2017 - Reusing Your Reuse: How to Keep the Reuse You Have When You Move to DITA

Recommended

Recommended

More Related Content

Similar to LavaCon 2017 - Reusing Your Reuse: How to Keep the Reuse You Have When You Move to DITA

Similar to LavaCon 2017 - Reusing Your Reuse: How to Keep the Reuse You Have When You Move to DITA (20)

More from Jack Molisani

More from Jack Molisani (20)

Recently uploaded

Recently uploaded (20)

LavaCon 2017 - Reusing Your Reuse: How to Keep the Reuse You Have When You Move to DITA

Editor's Notes