copy-to usage

Expected Behavior

Hello everyone! I have faced the situation when the theory is not enough to understand how a certain feature works. I am talking about the copy-to attribute usage. I know that it is quite a basic thing, but I cannot find any samples on the Internet.

The description at oxygenxml.com says: “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.”

Actual Behavior

I tried to add this attribute, but I cannot figure out the following:

• Where should the copy-to attribute go? After the original file that I want to duplicate?
• How I can actually reuse the duplicated topic? So if I want to use topic_1.dita one more time in the same map, how should I do it?
• I tried several options and could not find the right place for topicmeta usage - to add an alternative title, for example.

Environment

• DITA-OT version: 3.0.4
• Operating system and version: Windows
• How did you run DITA-OT: The dita command
• Transformation type: PDF

Thank you in advance!

new_map.zip

[drmacro]

Here is the description of @copy-to in the DITA spec:

@copy-to Use the @copy-to attribute on the <topicref> element to provide a different resource name for a particular instance of a resource referenced by the <topicref> (for example, to separate out the different versions of the topic, rather than combining them on output). If applicable, the @copy-to value can include path information. The links and navigation associated with that instance will point to a copy of the topic with the file name you specified. Applications MAY support @copy-to for references to local non-DITA resources. The @copy-to attribute is not supported for references to resources where the effective value for @scope is “peer” or “external”.

Use the <linktext> and <shortdesc> in the <topicref>'s <topicmeta> to provide a unique name and short description for the new copy.

(http://docs.oasis-open.org/dita/dita/v1.3/errata01/os/complete/part1-base/langRef/attributes/topicrefElementAttributes.html#topicref-element-atts)

The Oxygen language you quote is not quite accurate in that @copy-to does not specify the effective result filename, it specifies the effective source filename, which may (or may not) then affect the result filename if the referenced topic happens to result in a separate file in the rendition (e.g., you’re generating HTML).

The best way to refer to topics on which you’ve used @copy-to is to use keys and key references. That ensures that you’re referring to the exact use of the topic you intend, e.g.:

<topicref keys="topic-a-use-1" href="topics/topic-a.dita"/>
<topicref keys="topic-a-use-2" href="topics/topic-a.dita" copy-to="topics/topic-a-02.dita"/>

Then in a topic an xref like <xref keyref="topic-a-use-2"/> can only mean “use the use of topic-a.dita with the key ‘topic-a-use-2’, which happens to have the effective source file name ‘topics/topic-a-02.dita’”

If for some reason the use of keys is not possible, then you can refer to the effective URL of the topic as defined by @copy-to and the processor should correctly resolve it. That is, the behavior should be identical to having made a literal copy of the topic with the name defined by @copy-to and referenced by that name.

[raducoravu]

@drmacro That particular topic from our web site is part of the DITA Style Guide by dr. Tony Self. Being a style guide it is less technical and probably tries to focus on the general benefits of using copy-to instead of copying the description in the specs.