DITA: reuse the same text multiple times with different variable setting for each instance

Question

I'm working on a document where, among other things, I need to explain two units that are very similar. I want to reuse text in both descriptions, but I want to use the name of the units in the shared text, and to configure a form of substitution/variable so the name of the units appear in each description. Note that the description of both units appear in the final document.

We're using a structure like this:

top.ditamap, which includes:
units_a_and_b.ditamap, which includes:
unit_a.dita
unit_b.dita

and then this file with text snippets:

unit_a_b_shared.dita

unit_a.dita and unit_b.dita will conref text snippets from unit_a_b_shared.dita.

So basically I want unit_a_b_shared.dita to contain something like this:

"When you configure DOODAA to ..."

and then I want DOODAA to be replaced with unit_a inside the unit_a part of the document, and with unit_b inside the unit_b part.

I've tried to use keywords for this, but so far without success. I haven't found a way to make them take on different values in the different files, even when using keyscopes as explained here: https://blog.oxygenxml.com/keyscopes/keyscopesBlog.html

The problem seems to be that with keyscopes I need the full path, which includes which unit it is, and hence cannot be used in the text snippet which is shared. Without keyscopes the first definition of the keyword applies everywhere.

Any suggestions on how to achieve this goal (using keywords or not)?

Answer 1

I wrote that key scopes article on the Oxygen XML Blog and I think that key scopes seem to be the answer for your case. So the "unit_a_b_shared.dita" file would have inside a something like:

<p id="reusablePara">some text before <ph keyref="unit"/> some text after</p>

And then in the DITA Map you would refer to ""unit_a_b_shared.dita"" in different key scopes and re-define the key "unit" in those places to bind it to a different value. The DITA Map would need to look like this:

    <map>
        <title>Main</title>
        <topicref href="unit_a.dita" keyscope="unitA">
            <keydef href="unit_a_b_shared.dita" keys="reusables"/>
            <keydef keys="unit">
                <topicmeta>
                    <keywords>
                        <keyword>KM</keyword>
                    </keywords>
                </topicmeta>
            </keydef>
        </topicref>
        <topicref href="unit_b.dita" keyscope="unitB">
            <keydef href="unit_a_b_shared.dita" keys="reusables"/>
            <keydef keys="unit">
                <topicmeta>
                    <keywords>
                        <keyword>KG</keyword>
                    </keywords>
                </topicmeta>
            </keydef>
        </topicref>
    </map>

and inside "unit_a.dita" you would conkeyref to the reusable paragraph inside the "unit_a_b_shared.dita" file:

        <p conkeyref="reusables/reusableParagraph"/>

Note that I'm using "conkeyref" not "conref". Once you get to use key scopes you should avoid direct links or direct content references, use only indirect linking using keys.