<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>oXygen XML Editor Blog</title>
</head>
<body>
<style type="text/css">
h1 a:hover {background-color:#888;color:#fff ! important;}
div#emailbody table#itemcontentlist tr td div ul {
list-style-type:square;
padding-left:1em;
}
div#emailbody table#itemcontentlist tr td div blockquote {
padding-left:6px;
border-left: 6px solid #dadada;
margin-left:1em;
}
div#emailbody table#itemcontentlist tr td div li {
margin-bottom:1em;
margin-left:1em;
}
table#itemcontentlist tr td a:link, table#itemcontentlist tr td a:visited, table#itemcontentlist tr td a:active, ul#summarylist li a {
color:#000099;
font-weight:bold;
text-decoration:none;
}
img {border:none;}
</style>
<div xmlns="http://www.w3.org/1999/xhtml" id="emailbody" style="margin:0 2em;font-family:Georgia,Helvetica,Arial,Sans-Serif;line-height:140%;font-size:13px;color:#000000;">
<table style="border:0;padding:0;margin:0;width:100%">
<tr>
<td style="vertical-align:top" width="99%">
<h1 style="margin:0;padding-bottom:6px;">
<a style="color:#888;font-size:22px;font-family:Arial, Helvetica, sans-serif;font-weight:normal;text-decoration:none;" href="http://blog.oxygenxml.com/" title="(http://blog.oxygenxml.com/)">[oXygen XML Editor Blog] - DITA Linking Strategies</a>
</h1>
</td>
<td width="1%" />
</tr>
</table>
<hr style="border:1px solid #ccc;padding:0;margin:0" />
<table id="itemcontentlist">
<tr xmlns="">
<td style="margin-bottom:0;line-height:1.4em;">
<p style="margin:1em 0 3px 0;">
<a name="1" style="font-family:Arial, Helvetica, sans-serif;font-size:18px;" href="http://feedproxy.google.com/~r/AboutOxygenXmlEditor/~3/NkzlLkUcD9Q/dita-linking-strategies.html?utm_source=feedburner&utm_medium=email">DITA Linking Strategies</a>
</p>
<p style="font-size:13px;color:#555;margin:9px 0 3px 0;font-family:Georgia,Helvetica,Arial,Sans-Serif;line-height:140%;font-size:13px;">
<span>Posted:</span> 30 Jun 2017 06:11 AM PDT</p>
<div style="margin:0;font-family:Georgia,Helvetica,Arial,Sans-Serif;line-height:140%;font-size:13px;color:#000000;"><div class="body"> <p class="p">This small tutorial is based on the "DITA Linking Strategies" presentations I made for the DITA Europe 2016 and DITA North America 2017 conferences. It's a general overview about DITA linking possibilities and best practices. Also, it's meant as a continuation of the <a class="xref" href="http://blog.oxygenxml.com/2015/11/dita-reuse-strategies-short-tutorial.html" target="_blank">DITA Reuse Strategies</a> blog post.</p> <p class="p">According to <a class="xref" href="https://en.wikipedia.org/wiki/Hyperlink" target="_blank">Wikipedia</a>: <blockquote class="lq">"A link, is a reference to data that the reader can directly follow either by clicking, tapping, or hovering."</blockquote></p> <p class="p">Basically, we should regard linking as yet another form of content reuse, except that instead of presenting the content in place, it re-directs the end user to some other resource.</p> <p class="p">I'll start with describing linking at DITA Map level.</p> <div class="section" id="dita_linking_stretegies__section_bt2_hpz_j1b"><h2 class="title sectiontitle">Map-Level Linking</h2> <div class="p">A DITA Map uses topic references to assemble the content of a publication.<pre class="pre codeblock language-xml"> <strong class="hl-tag" style="color:#000096"><topicref</strong> <span class="hl-attribute" style="color: #ff7935">href</span>=<span class="hl-value" style="color: #993300">"installation.dita"</span><strong class="hl-tag" style="color:#000096">></strong><br /> <strong class="hl-tag" style="color:#000096"><topicref</strong> <span class="hl-attribute" style="color: #ff7935">href</span>=<span class="hl-value" style="color: #993300">"server_installation.dita"</span><strong class="hl-tag" style="color:#000096">/></strong><br /> <strong class="hl-tag" style="color:#000096"><topicref</strong> <span class="hl-attribute" style="color: #ff7935">href</span>=<span class="hl-value" style="color: #993300">"client_side_installation.dita"</span><strong class="hl-tag" style="color:#000096">/></strong><br /> <strong class="hl-tag" style="color:#000096"></topicref></strong></pre></div> <p class="p">Depending on the output format, the topic reference may be a link in the table of contents for the XHTML-based outputs or it may be interpreted as a content reference for the PDF-based output that generates a single monolith document. So the role of the <code class="ph codeph">topicref</code> is dual, it may sometimes be regarded as a link to a topic and sometimes as a content reference.</p> </div> <div class="section" id="dita_linking_stretegies__section_d5k_rpz_j1b"><h2 class="title sectiontitle">Chunking</h2> <p class="p">DITA topic modules should be kept as small as possible, but sometimes the end user may need to read more than one topic to achieve a single task. So, when publishing to HTML-based outputs, you will end up asking yourself this question:<blockquote class="lq">Should I prefer larger HTML files or more links in the TOC?</blockquote></p> <div class="p">And you should always consider these two ideas:<ul class="ul" id="dita_linking_stretegies__ul_ffy_brz_j1b"> <li class="li"> <p class="p">Links are disruptive. Ideally, users would not need to jump around in content to read the entire story they are searching for. </p> </li> <li class="li">Small topics that are usually read consecutively by the end user can probably get merged together.</li> </ul></div> <div class="p">For example, if the installation of your product requires installing both a server-side and a client-side component, by using DITA chunking you can choose to have separate DITA topic modules for each of the installation procedures but merge the topics together in the web-based outputs:<pre class="pre codeblock language-xml"><strong class="hl-tag" style="color:#000096"><map></strong><br /> <strong class="hl-tag" style="color:#000096"><title></strong>User Guide<strong class="hl-tag" style="color:#000096"></title></strong><br /> <strong class="hl-tag" style="color:#000096"><topicref</strong> <span class="hl-attribute" style="color: #ff7935">href</span>=<span class="hl-value" style="color: #993300">"installation.dita"</span> <span class="hl-attribute" style="color: #ff7935">chunk</span>=<span class="hl-value" style="color: #993300">"to-content"</span><strong class="hl-tag" style="color:#000096">></strong><br /> <strong class="hl-tag" style="color:#000096"><topicref</strong> <span class="hl-attribute" style="color: #ff7935">href</span>=<span class="hl-value" style="color: #993300">"server_installation.dita"</span> <span class="hl-attribute" style="color: #ff7935">toc</span>=<span class="hl-value" style="color: #993300">"no"</span><strong class="hl-tag" style="color:#000096">/></strong><br /> <strong class="hl-tag" style="color:#000096"><topicref</strong> <span class="hl-attribute" style="color: #ff7935">href</span>=<span class="hl-value" style="color: #993300">"client_side_installation.dita"</span> <span class="hl-attribute" style="color: #ff7935">toc</span>=<span class="hl-value" style="color: #993300">"no"</span><strong class="hl-tag" style="color:#000096">/></strong><br /> <strong class="hl-tag" style="color:#000096"></topicref></strong><br /><strong class="hl-tag" style="color:#000096"></map></strong></pre></div> <p class="p">You can read more about chunking in the <a class="xref" href="http://docs.oasis-open.org/dita/dita/v1.3/os/part3-all-inclusive/archSpec/base/chunking.html" target="_blank">DITA 1.3 specification</a>. The <a class="xref" href="https://www.oxygenxml.com/dita/styleguide/webhelp-feedback/#Artefact/Topics_and_Information_Types/c_Avoiding_Hierarchy_in_Topics.html" target="_blank">DITA Style Guide</a> also has a good overview about why it is preferable to write small topics and then merge them together using the chunking mechanism.</p> </div> <div class="section" id="dita_linking_stretegies__section_bhr_grz_j1b"><h2 class="title sectiontitle">Topic-Level Linking</h2> <p class="p">Links that appear inside topics can be divided into various categories and I'll discuss each of these categories separately.</p> </div> <div class="section" id="dita_linking_stretegies__section_adf_ysz_j1b"><h2 class="title sectiontitle">In-Content Links</h2> <div class="p">In-content links are links added manually in the topic content:<pre class="pre codeblock language-xml"><strong class="hl-tag" style="color:#000096"><li></strong>See: <strong class="hl-tag" style="color:#000096"><xref</strong> <span class="hl-attribute" style="color: #ff7935">href</span>=<span class="hl-value" style="color: #993300">"http://www.../"</span> <span class="hl-attribute" style="color: #ff7935">format</span>=<span class="hl-value" style="color: #993300">"html"</span> <span class="hl-attribute" style="color: #ff7935">scope</span>=<span class="hl-value" style="color: #993300">"external"</span><strong class="hl-tag" style="color:#000096">/></strong><strong class="hl-tag" style="color:#000096"></li></strong></pre></div> <p class="p">You should keep in mind that this kind of link is disruptive to the reading experience because when end users encounter them, they need to decide weather to read further on or to follow the link. On the other hand, this may sometimes be a good thing. For example, one of the installation steps may require the end user to download a certain library from an external website before continuing.</p> <p class="p">You can read more about links in general in the <a class="xref" href="http://docs.oasis-open.org/dita/dita/v1.3/os/part3-all-inclusive/langRef/base/xref.html" target="_blank">DITA 1.3 specification</a>. The <a class="xref" href="https://www.oxygenxml.com/dita/styleguide/webhelp-feedback/Artefact/Cross_Referencing/c_Avoiding_Cross_References.html" target="_blank">DITA Style Guide</a>, written by Tony Self, also discourages the use of in-content links.</p> </div> <div class="section" id="dita_linking_stretegies__section_tfx_ttz_j1b"><h2 class="title sectiontitle">Related Links</h2> <div class="p">Related links are placed at the end of the DITA topic and they allow the end user to explore additional resources after the current topic has been read.<pre class="pre codeblock language-xml"><strong class="hl-tag" style="color:#000096"><related-links></strong><br /> <strong class="hl-tag" style="color:#000096"><link</strong> <span class="hl-attribute" style="color: #ff7935">href</span>=<span class="hl-value" style="color: #993300">"http://tomcat.apache.org/"</span> <span class="hl-attribute" style="color: #ff7935">format</span>=<span class="hl-value" style="color: #993300">"html"</span> <span class="hl-attribute" style="color: #ff7935">scope</span>=<span class="hl-value" style="color: #993300">"external"</span><strong class="hl-tag" style="color:#000096">/></strong><br /><strong class="hl-tag" style="color:#000096"></related-links></strong></pre></div> <p class="p">To minimize disruption when reading the content in general, the preferred place where to place links is at the end of the generated HTML page.</p> <p class="p">You can read more about related links in the <a class="xref" href="http://docs.oasis-open.org/dita/dita/v1.3/os/part3-all-inclusive/langRef/base/related-links.html" target="_blank">DITA 1.3 specification</a>.</p> </div> <div class="section" id="dita_linking_stretegies__section_gtq_k5z_j1b"><h2 class="title sectiontitle">Defining Related Links using Relationship Tables</h2> <div class="p">Related links do not need to be manually added at the end of each topic. You can define relationship tables in the DITA Map:<pre class="pre codeblock language-xml"><strong class="hl-tag" style="color:#000096"><reltable></strong><br /> <strong class="hl-tag" style="color:#000096"><relrow></strong><br /> <strong class="hl-tag" style="color:#000096"><relcell></strong><br /> <strong class="hl-tag" style="color:#000096"><topicref</strong> <span class="hl-attribute" style="color: #ff7935">href</span>=<span class="hl-value" style="color: #993300">"client_side_installation.dita"</span><strong class="hl-tag" style="color:#000096">/></strong><br /> <strong class="hl-tag" style="color:#000096"></relcell></strong><br /> <strong class="hl-tag" style="color:#000096"><relcell></strong><br /> <strong class="hl-tag" style="color:#000096"><topicref</strong> <span class="hl-attribute" style="color: #ff7935">href</span>=<span class="hl-value" style="color: #993300">"server_installation.dita"</span><strong class="hl-tag" style="color:#000096">/></strong><br /> <strong class="hl-tag" style="color:#000096"></relcell></strong><br /> <strong class="hl-tag" style="color:#000096"></relrow></strong><br /> ……..<br /> <strong class="hl-tag" style="color:#000096"></reltable></strong></pre></div> <p class="p">These tables can define associations between two or more topics, associations that automatically contribute to the related links creation in the generated HTML output.</p> <div class="p">Here are some benefits of using relationship tables:<ul class="ul" id="dita_linking_stretegies__ul_sgb_hvz_j1b"> <li class="li"> <p class="p">A topic should have as few links as possible defined directly within. This makes it easier to reuse the topic in various contexts and keeps it as separate as possible for other parts of the DITA project, decreasing the possibility of broken links.</p> </li> <li class="li"> <p class="p"> By default, links defined in relationship tables are bi-directional, allowing users to land on any of the topics when searching for solutions and find their way to the related ones.</p> </li> <li class="li"> <p class="p"> Using a relationship table separates the task of writing topics from the task of finding relationships between topics.</p> </li> </ul></div> <p class="p">You can read more about relationship tables in the <a class="xref" href="http://docs.oasis-open.org/dita/dita/v1.3/os/part3-all-inclusive/langRef/base/reltable.html" target="_blank">DITA 1.3 specification</a>. The <a class="xref" href="https://www.oxygenxml.com/dita/styleguide/webhelp-feedback/index.html#Artefact/Cross_Referencing/c_Related_Links_Section.html" target="_blank">DITA Style Guide</a> also recommends using relationship tables.</p> </div> <div class="section" id="dita_linking_stretegies__section_aw2_pzz_j1b"><h2 class="title sectiontitle">Indirect Links (Key References)</h2> <div class="p">All the link samples we've look at so far have been direct links, links that point to the target using the <code class="keyword markupname xmlatt">@href</code> attribute. Indirect links require two steps:<ol class="ol" id="dita_linking_stretegies__ol_l4g_b11_k1b"> <li class="li">Define a key in the DITA Map for the target.<pre class="pre codeblock language-xml"><strong class="hl-tag" style="color:#000096"><keydef</strong> <span class="hl-attribute" style="color: #ff7935">keys</span>=<span class="hl-value" style="color: #993300">"client_installation"</span> <span class="hl-attribute" style="color: #ff7935">href</span>=<span class="hl-value" style="color: #993300">"client_side_installation.dita"</span><strong class="hl-tag" style="color:#000096">/></strong></pre></li> <li class="li">Use the defined key to reference the target resources.<pre class="pre codeblock language-xml"><strong class="hl-tag" style="color:#000096"><xref</strong> <span class="hl-attribute" style="color: #ff7935">keyref</span>=<span class="hl-value" style="color: #993300">"client_installation"</span><strong class="hl-tag" style="color:#000096">/></strong></pre></li> </ol></div> <div class="p">Here are some of the benefits of indirect linking:<ul class="ul" id="dita_linking_stretegies__ul_ubv_m11_k1b"> <li class="li"> <div class="p">Offers the ability to reuse link target text and meta data. If you want to have custom text for a certain link, you can define it directly in the DITA Map:<pre class="pre codeblock language-xml"><strong class="hl-tag" style="color:#000096"><keydef</strong> <span class="hl-attribute" style="color: #ff7935">keys</span>=<span class="hl-value" style="color: #993300">"dita_ot_website"</span> <span class="hl-attribute" style="color: #ff7935">href</span>=<span class="hl-value" style="color: #993300">"http://www.dita-ot.org/"</span> <span class="hl-attribute" style="color: #ff7935">format</span>=<span class="hl-value" style="color: #993300">"html"</span><br /> <span class="hl-attribute" style="color: #ff7935">scope</span>=<span class="hl-value" style="color: #993300">"external"</span><strong class="hl-tag" style="color:#000096">></strong><br /> <strong class="hl-tag" style="color:#000096"><topicmeta></strong><br /> <strong class="hl-tag" style="color:#000096"><linktext></strong>DITA Open Toolkit Web Site<strong class="hl-tag" style="color:#000096"></linktext></strong><br /> <strong class="hl-tag" style="color:#000096"></topicmeta></strong><br /> <strong class="hl-tag" style="color:#000096"></keydef></strong></pre>and then add key references in all other places:<pre class="pre codeblock language-xml"><strong class="hl-tag" style="color:#000096"><xref</strong> <span class="hl-attribute" style="color: #ff7935">keyref</span>=<span class="hl-value" style="color: #993300">"dita_ot_website"</span><strong class="hl-tag" style="color:#000096">/></strong></pre></div> </li> <li class="li"> <div class="p">Easier conditional linking (including links to topics that sometimes may be missing). If you want your topic to link either to one target or to another depending on the filtering/profiling conditions, instead of adding profiling directly on the link, you can add the profiling conditions directly in the DITA Map:<pre class="pre codeblock language-xml"> <strong class="hl-tag" style="color:#000096"><topicref</strong> <span class="hl-attribute" style="color: #ff7935">keys</span>=<span class="hl-value" style="color: #993300">"slicing"</span> <span class="hl-attribute" style="color: #ff7935">href</span>=<span class="hl-value" style="color: #993300">"slicing_vegetables_for_experts.dita"</span> <span class="hl-attribute" style="color: #ff7935">audience</span>=<span class="hl-value" style="color: #993300">"expert"</span><strong class="hl-tag" style="color:#000096">/></strong><br /> <strong class="hl-tag" style="color:#000096"><topicref</strong> <span class="hl-attribute" style="color: #ff7935">keys</span>=<span class="hl-value" style="color: #993300">"slicing"</span> <span class="hl-attribute" style="color: #ff7935">href</span>=<span class="hl-value" style="color: #993300">"slicing_vegetables_for_novices.dita"</span> <span class="hl-attribute" style="color: #ff7935">audience</span>=<span class="hl-value" style="color: #993300">"novice"</span><strong class="hl-tag" style="color:#000096">/></strong><br /> <strong class="hl-tag" style="color:#000096"><keydef</strong> <span class="hl-attribute" style="color: #ff7935">keys</span>=<span class="hl-value" style="color: #993300">"slicing"</span> <span class="hl-attribute" style="color: #ff7935">audience</span>=<span class="hl-value" style="color: #993300">"noLink"</span><strong class="hl-tag" style="color:#000096">></strong><strong class="hl-tag" style="color:#000096"><topicmeta></strong><strong class="hl-tag" style="color:#000096"><keywords></strong><br /> <strong class="hl-tag" style="color:#000096"><keyword></strong>Slicing<strong class="hl-tag" style="color:#000096"></keyword></strong><strong class="hl-tag" style="color:#000096"></keywords></strong><strong class="hl-tag" style="color:#000096"></topicmeta></strong><br /> <strong class="hl-tag" style="color:#000096"></keydef></strong></pre>and then link to the key from each topic: <pre class="pre codeblock"><code><xref keyref="slicing"/></code></pre></div> </li> <li class="li"> <p class="p">Easier link management. A good overview about all the outbound links in your project helps you maintain and control lists of allowed external web sites. With indirect references, you can define all references to external resources in a separate DITA Map. An example of a DITA project using indirect links to achieve separation of links by purpose can be found here: <a class="xref" href="https://github.com/oxygenxml/dita-project-best-practices" target="_blank">https://github.com/oxygenxml/dita-project-best-practices</a>.</p> </li> <li class="li">Makes it easier to move/rename topics. When you move or rename a topic referenced via indirect links, only the link defined in the DITA Map will break, making it easier to fix broken links.</li> </ul></div> <p class="p">There is an overview about indirect addressing on the <a class="xref" href="http://dita.xml.org/resource/keyref-overview-dita-12" target="_blank">DITA XML Org</a> website. The <a class="xref" href="https://www.oxygenxml.com/dita/1.3/specs/archSpec/base/key-based-addressing.html" target="_blank">DITA 1.3 specification</a> also has a chapter about indirect links.</p> </div> <div class="section" id="dita_linking_stretegies__section_bnr_nf1_k1b"><h2 class="title sectiontitle">Auto-Generated Links</h2> <div class="p">Until now, I've talked about manually added links, either in the topic or in relationship tables. Using the DITA <code class="keyword markupname xmlatt">@collection-type</code> attribute, you can define relationships between parent and child topic references in the DITA Map, relationships that result in automatic links added between them:<pre class="pre codeblock language-xml"> <strong class="hl-tag" style="color:#000096"><topicref</strong> <span class="hl-attribute" style="color: #ff7935">href</span>=<span class="hl-value" style="color: #993300">"installation.dita"</span> <span class="hl-attribute" style="color: #ff7935">collection-type</span>=<span class="hl-value" style="color: #993300">"sequence"</span><strong class="hl-tag" style="color:#000096">></strong><br /> <strong class="hl-tag" style="color:#000096"><topicref</strong> <span class="hl-attribute" style="color: #ff7935">href</span>=<span class="hl-value" style="color: #993300">"server_installation.dita"</span><strong class="hl-tag" style="color:#000096">/></strong><br /> <strong class="hl-tag" style="color:#000096"><topicref</strong> <span class="hl-attribute" style="color: #ff7935">href</span>=<span class="hl-value" style="color: #993300">"client_side_installation.dita"</span><strong class="hl-tag" style="color:#000096">/></strong><br /> <strong class="hl-tag" style="color:#000096"></topicref></strong></pre> There are 3 useful types of <code class="keyword markupname xmlatt">@collection-type</code> values:<ul class="ul" id="dita_linking_stretegies__ul_jlv_cg1_k1b"> <li class="li"> <p class="p"><strong class="ph b">Unordered</strong> - Links are generated from parent to children, and from children to parent. </p> </li> <li class="li"> <p class="p"><strong class="ph b">Family</strong> - Links are generated from parent to children, from children to parent, and from sibling to sibling. </p> </li> <li class="li"> <p class="p"><strong class="ph b">Sequence</strong> - Links are generated from parent to children, from children to parent, and from child to previous sibling (if applicable) and next sibling (if applicable). </p> </li> </ul></div> <p class="p">You can read more about auto-generated links in the <a class="xref" href="https://www.oxygenxml.com/dita/styleguide/webhelp-feedback/#Artefact/Maps/c_Collection_Types.html" target="_blank">DITA Style Guide</a>.</p> </div> <div class="section" id="dita_linking_stretegies__section_syb_kh1_k1b"><h2 class="title sectiontitle">Conditional Links in Distinct Publications</h2> <p class="p">You may publish documentation for multiple products from the same <strong class="ph b">DITA</strong> content. Also, you may want to have links point to various targets depending on the product for which you want to publish the documentation. Or, you may want to suppress links completely in certain publications.</p> <div class="p">When using direct linking, you will need to profile each link depending on the publication:<pre class="pre codeblock language-xml">Find our more about slicing vegetables: <strong class="hl-tag" style="color:#000096"><xref</strong> <span class="hl-attribute" style="color: #ff7935">href</span>=<span class="hl-value" style="color: #993300">"slicing_vegetables_for_experts.dita"</span> <span class="hl-attribute" style="color: #ff7935">audience</span>=<span class="hl-value" style="color: #993300">"expert"</span><strong class="hl-tag" style="color:#000096">/></strong><br /><strong class="hl-tag" style="color:#000096"><xref</strong> <span class="hl-attribute" style="color: #ff7935">href</span>=<span class="hl-value" style="color: #993300">"slicing_vegetables_for_novices.dita"</span> <span class="hl-attribute" style="color: #ff7935">audience</span>=<span class="hl-value" style="color: #993300">"novice"</span><strong class="hl-tag" style="color:#000096">/></strong>.</pre>With indirect links, you can define the profiling attributes as DITA Map level:<pre class="pre codeblock language-xml"> <strong class="hl-tag" style="color:#000096"><topicref</strong> <span class="hl-attribute" style="color: #ff7935">keys</span>=<span class="hl-value" style="color: #993300">"slicing"</span> <span class="hl-attribute" style="color: #ff7935">href</span>=<span class="hl-value" style="color: #993300">"slicing_vegetables_for_experts.dita"</span> <span class="hl-attribute" style="color: #ff7935">audience</span>=<span class="hl-value" style="color: #993300">"expert"</span><strong class="hl-tag" style="color:#000096">/></strong><br /> <strong class="hl-tag" style="color:#000096"><topicref</strong> <span class="hl-attribute" style="color: #ff7935">keys</span>=<span class="hl-value" style="color: #993300">"slicing"</span> <span class="hl-attribute" style="color: #ff7935">href</span>=<span class="hl-value" style="color: #993300">"slicing_vegetables_for_novices.dita"</span> <span class="hl-attribute" style="color: #ff7935">audience</span>=<span class="hl-value" style="color: #993300">"novice"</span><strong class="hl-tag" style="color:#000096">/></strong></pre>and thus, simplify the reference made in the topic content:<pre class="pre codeblock language-xml">Find our more about slicing vegetables: <strong class="hl-tag" style="color:#000096"><xref</strong> <span class="hl-attribute" style="color: #ff7935">keyref</span>=<span class="hl-value" style="color: #993300">"slicing/>.</span></pre></div> </div> <div class="section" id="dita_linking_stretegies__section_f34_431_k1b"><h2 class="title sectiontitle">Conditional Links in the Same Publication</h2><div class="p">Using DITA 1.3 key scopes, you can reuse a topic multiple times in a DITA Map and have each referenced topic contain links to various target topics. For example, if my <span class="ph filepath">preparing_vegetables.dita</span> topic has a link:<pre class="pre codeblock language-xml"><strong class="hl-tag" style="color:#000096"><link</strong> <span class="hl-attribute" style="color: #ff7935">keyref</span>=<span class="hl-value" style="color: #993300">"slicing"</span><strong class="hl-tag" style="color:#000096">/></strong></pre></div>you can define various key scopes in the DITA Map that bind the "slicing" key to various targets:<pre class="pre codeblock language-xml"> <strong class="hl-tag" style="color:#000096"><topichead</strong> <span class="hl-attribute" style="color: #ff7935">navtitle</span>=<span class="hl-value" style="color: #993300">"Cooking for Experts"</span> <span class="hl-attribute" style="color: #ff7935">keyscope</span>=<span class="hl-value" style="color: #993300">"expert"</span><strong class="hl-tag" style="color:#000096">></strong><br /> <strong class="hl-tag" style="color:#000096"><topicref</strong> <span class="hl-attribute" style="color: #ff7935">href</span>=<span class="hl-value" style="color: #993300">"preparing_vegetables.dita"</span> <span class="hl-attribute" style="color: #ff7935">keys</span>=<span class="hl-value" style="color: #993300">"preparing"</span><strong class="hl-tag" style="color:#000096">/></strong><br /> <strong class="hl-tag" style="color:#000096"><topicref</strong> <span class="hl-attribute" style="color: #ff7935">href</span>=<span class="hl-value" style="color: #993300">"slicing_vegetables_for_experts.dita"</span> <span class="hl-attribute" style="color: #ff7935">keys</span>=<span class="hl-value" style="color: #993300">"slicing"</span><strong class="hl-tag" style="color:#000096">/></strong><br /> <strong class="hl-tag" style="color:#000096"></topichead></strong><br /> <strong class="hl-tag" style="color:#000096"><topichead</strong> <span class="hl-attribute" style="color: #ff7935">navtitle</span>=<span class="hl-value" style="color: #993300">"Cooking for Novices"</span> <span class="hl-attribute" style="color: #ff7935">keyscope</span>=<span class="hl-value" style="color: #993300">"novice"</span><strong class="hl-tag" style="color:#000096">></strong><br /> <strong class="hl-tag" style="color:#000096"><topicref</strong> <span class="hl-attribute" style="color: #ff7935">href</span>=<span class="hl-value" style="color: #993300">"preparing_vegetables.dita"</span> <span class="hl-attribute" style="color: #ff7935">keys</span>=<span class="hl-value" style="color: #993300">"preparing"</span><strong class="hl-tag" style="color:#000096">/></strong><br /> <strong class="hl-tag" style="color:#000096"><topicref</strong> <span class="hl-attribute" style="color: #ff7935">href</span>=<span class="hl-value" style="color: #993300">"slicing_vegetables_for_novices.dita"</span> <span class="hl-attribute" style="color: #ff7935">keys</span>=<span class="hl-value" style="color: #993300">"slicing"</span><strong class="hl-tag" style="color:#000096">/></strong><br /> <strong class="hl-tag" style="color:#000096"></topichead></strong></pre><p class="p">This previous <a class="xref" href="http://blog.oxygenxml.com/2015/08/dita-13-key-scopes-next-generation-of.html" target="_blank">blog post</a> contains more details about key scopes.</p></div> <div class="section" id="dita_linking_stretegies__section_ct2_qg1_k1b"><h2 class="title sectiontitle">Link Text</h2> <p class="p">When linking to an external resource or to a DITA topic or element, the publishing engine will attempt to deduce the link text from the target context. For example, the link to a DITA topic or element that contains a <code class="keyword markupname xmlelement"><title></code> will use that title as the link text. The link to an external resource (for example to <strong class="ph b">http://www.oxygenxml.com</strong>) will, by default, use the <strong class="ph b">HTTP</strong> location as the link text. You can also customize each link text individually. So, ask yourself this question:</p> <p class="p"> <blockquote class="lq">Should I leave the link text to be automatically computed or should I set a more friendly text?</blockquote> </p> <p class="p">For internal links to elements that have a title, in general it is more flexible to not set a custom text and let the publishing engine decide one for you. For external links, you should usually specify your custom link text. </p> </div> <div class="section" id="dita_linking_stretegies__section_wtf_vj1_k1b"><h2 class="title sectiontitle">Should I Link or Should I Reuse?</h2> <p class="p">Suppose you want to bring a certain paragraph, note, or section to the end user's attention. If that particular target element is not very large, you should always reuse it (using a content reference) instead of linking to it.</p> </div> <div class="section" id="dita_linking_stretegies__section_rzj_gj1_k1b"><h2 class="title sectiontitle">Conclusions</h2> <div class="p">As with all large projects, managing links in a growing <strong class="ph b">DITA</strong> project can be problematic, so you need to become organized. As an overview of what we've discussed so far, I suggest the following best practices:<ul class="ul" id="dita_linking_stretegies__ul_hqm_nj1_k1b"> <li class="li"> <p class="p">Linking is a form of reuse so:</p> <ul class="ul" id="dita_linking_stretegies__ul_cdc_pj1_k1b"> <li class="li">Reuse small pieces of content instead of linking to them</li> <li class="li">Avoid too much linking (linking is disruptive)</li> </ul> </li> <li class="li"> <p class="p">Use indirect links. It will allow you to reuse link text and make profiling/filtering easier while giving you a better overview of the outbound links for your project.</p> </li> </ul></div> </div> <p class="p">If you want to experiment with the various linking strategies I discussed above, you can find some samples here: <a class="xref" href="https://www.oxygenxml.com/forum/files/linking-strategies-samples.zip" target="_blank">https://www.oxygenxml.com/forum/files/linking-strategies-samples.zip</a>.</p> </div><img src="http://feeds.feedburner.com/~r/AboutOxygenXmlEditor/~4/NkzlLkUcD9Q?utm_source=feedburner&utm_medium=email" height="1" width="1" alt=""/></div>
</td>
</tr>
</table>
<table style="border-top:1px solid #999;padding-top:4px;margin-top:1.5em;width:100%" id="footer">
<tr>
<td style="text-align:left;font-family:Helvetica,Arial,Sans-Serif;font-size:11px;margin:0 6px 1.2em 0;color:#333;">You are subscribed to email updates from <a href="http://blog.oxygenxml.com/">oXygen XML Editor Blog</a>.<br />To stop receiving these emails, you may <a href="https://feedburner.google.com/fb/a/mailunsubscribe?k=y_tRXtumvTurKTedh51JnlYsGXw">unsubscribe now</a>.</td>
<td style="font-family:Helvetica,Arial,Sans-Serif;font-size:11px;margin:0 6px 1.2em 0;color:#333;text-align:right;vertical-align:top">Email delivery powered by Google</td>
</tr>
<tr>
<td colspan="2" style="text-align:left;font-family:Helvetica,Arial,Sans-Serif;font-size:11px;margin:0 6px 1.2em 0;color:#333;">Google Inc., 1600 Amphitheatre Parkway, Mountain View, CA 94043, United States</td>
</tr>
</table>
</div>
</body>
</html>