The copy-to attribute

The copy-to attribute of the topicref element is used in the unusual situation where you need to create two copies of the same topic in the output, and to link to each copy of the output topic separately. The value of the attribute is the file name of the duplicate.

You can use the copy-to attribute of the ditamap topicref element when you need the output file name to differ from what would otherwise be automatically generated, or when you need two or more identical or almost identical copies of the same topic in the output. The copies of the original topic can have different generated link text and generated short descriptions.

The value entered in the copy-to attribute is the duplicate file name, with a .dita extension. If you name the file ej25_special.dita, and generate to XHTML, the output file name will be ej25_special.html. The original topic file name will always be generated in the output; copy-to creates a duplicate file name, rather than modifying the file name.

The copy-to attribute will also let you apply different metadata attributes (even navtitle) for each reference in the map. For example, you could have one topic about saving data records, and use it in the ditamap twice as Saving Customer Records and Saving Staff Records.

The use of the copy-to attribute is appropriate in both the hierarchy section of the ditamap and the reltable section.

Note:
When using the DITA Open Toolkit, the file extension provided in the copy-to attribute must be .xml or .dita.

An example of when copy-to might be used to create two identical topics is as follows. A Microsoft HTML Help system is being developed, where the same topic needs to be displayed as a child of two different parent nodes in different parts of the TOC hierarchy. Microsoft HTML Help has a synchronise TOC function, and a sequential browsing function. If the same HTML topic is used in two different places in the TOC, the synchronise function will always highlight the first occurrence of the topic file name in the TOC pane, thus confusing the user who expects to see the topic in a different section of the Help system. Using the copy-to attribute to specify an alternative file name for the second instance in the DITA map file will result in two topics being generated during processing, and the synchronisation and other sequencing problems will not occur in the output.

You should only use the copy-to attribute in topicref elements in relationship tables when you need to create a second output file and you need to alter the topic's linking or short description characteristics in the second copy.

For example, you may want the information in a topic about turbochargers to appear in the output twice, and to be referenced in the Related Topics link group in one instance as XT Turbocharger Explained, but in another output topic's Related Topics link group as WRX Turbocharger Explained. In this case, you would enter the alternative linking text in a linktext element within a topicmeta element in the topicref, such as: 
<topicref href="turbo.dita" copy-to="xrw_turbo.dita">
  <topicmeta>
    <linktext>XRW Turbocharger Explained</linktext>
  </topicmeta>
</topicref>

Make sure you don't use the copy-to attribute when you only need to change the link text; in this case, the linktext element can be used alone.