View Categories

related-link

4 min read

Table of Contents

Syntax #

related-link((href=link)(type=target)(format=format)(scope=scope)(linktext=linktext)(desc=desc)(retain-content=))

href (optional)

the location of the target of the cross-reference. Must be in valid URI format.

type (optional)

describes the target of a cross-reference. Some possible values are fig, table, li, fn, section, concept, task, reference, topic, (no value).

format (optional)

format of the resource being linked to. Possible values are dita, html, pdf.

scope (optional)

describes the closeness of the relationship between the current document and the target. Possible values are local, peer, external.

linktext (optional)

the literal text for a link. Not needed for local links unless the local link is not in DITA format; needed for peer or external links.

desc (optional)

description of the element being cross-referenced.

retain-content (optional)

indicates whether or not the link text will be displayed. Possible values are true or false.

Purpose #

The order of the parameters is important; you do not have to use all of the parameters, but those that you do use must be in the order listed here.

Migrate will fill in the href and linktext by default, even if you do not specify them in the annotation. If you have text like the following in your document:

Document portion with related links

You could use the following rule, which does not specify either the href or the linktext:

Rule to add a related link with description

You would get the following for output.

<related-links>
  <link href="issue_3__task_procedure_authored_as_a_table_in_the_input_file.dita">
    <linktext>Issue 3: Task/Procedure authored as a table in the input file</linktext>
    <desc>Issue 3: Task/Procedure authored as a table in the input file</desc>
  </link>
  <link href="issue_6__a_definition_list_is_coded_as_a_table.dita">
    <linktext>Issue 6: A definition list is coded as a table</linktext>
    <desc>Issue 6: A definition list is coded as a table</desc>
  </link>
</related-links>

The following rule illustrates all of the parameters in use:

Rule for related links with all parameters in use

You would get the following for output.

  <p outputclass="ID-000002ae" otherprops="Online">Related Topics</p> 
  <xref outputclass="ID-0000013b" href="issue_3__task_procedure_authored_as_a_table_in_the_input_file.dita">
    Issue 3: Task/Procedure authored as a table in the input file
  </xref>
  <xref outputclass="ID-0000013b" href="issue_6__a_definition_list_is_coded_as_a_table.dita">
    Issue 6: A definition list is coded as a table
  </xref>
</conbody>
<related-links>
  <link href="ID-2316-000002fe" type="topic" format="dita" scope="local">
    <linktext>Issue 3: Task/Procedure authored as a table in the input file</linktext>
    <desc>Issue 3: Task/Procedure authored as a table in the input file</desc>
  </link>
  <link href="ID-2316-00000340" type="topic" format="dita" scope="local">
    <linktext>Issue 6: A definition list is coded as a table</linktext>
    <desc>Issue 6: A definition list is coded as a table </desc>
  </link>
</related-links>

The following rule illustrates all of the parameters in use, this time with retain-content set to false:

Rule for related links with all parameters in use, with retain-content=false

 

You would get the following for output.

  <p outputclass="ID-000002ae" otherprops="Online">Related Topics</p>
</conbody>
<related-links>
  <link href="ID-2316-000002fe" type="topic" format="dita" scope="local">
    <linktext>Issue 3: Task/Procedure authored as a table in the input file</linktext>
    <desc>Issue 3: Task/Procedure authored as a table in the input file</desc>
  </link>
  <link href="ID-2316-00000340" type="topic" format="dita" scope="local">
    <linktext>Issue 6: A definition list is coded as a table</linktext>
    <desc>Issue 6: A definition list is coded as a table</desc>
  </link>
</related-links>

This rule shows you how to specify no parameters at all, which will cause Migrate to fill in the defaults for href and linktext.

Rule for related links with no specified parameters

  <p outputclass="ID-000002ae" otherprops="Online">Related Topics</p>
</conbody>
<related-links>
  <link href="issue_3__task_procedure_authored_as_a_table_in_the_input_file.dita">
    <linktext>Issue 3: Task/Procedure authored as a table in the input file</linktext>
  </link>
  <link href="issue_6__a_definition_list_is_coded_as_a_table.dita">
    <linktext>Issue 6: A definition list is coded as a table</linktext>
  </link>
</related-links>
Annotations