Topics

Variable text referenced using keys


Kristen James Eberlein
 

Hi, DITA users.

I'm looking for information about how your implementations use keys for variable text. Variable text is text that you want to appear differently based on the context.

A couple of questions, for implementations that use keys to define variable text:

  1. What kind of content do you use variable text for? (Examples: product names, device names, product slogans or tag lines ...)
  2. What markup patterns do you use for key definition? For key referencing?
  3. Any pain points around variable text? Any particular successes? Things you wish were different?

For DITA 2.0, the DITA TC will be introducing simplified markup and processing for variable stuff referenced using keys. I am soliciting background information that will help inform our choices.

--
Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
OASIS Distinguished Contributor
Principal consultant, Eberlein Consulting LLC
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)


Chris Papademetrious
 

Hi Kris,

We use variables for

  • Product name
  • Product name, trademarked version
  • Product release version
  • Product release date
  • Product shell prompt (a software thing)

Some of our books are conditional across multiple products, and so we conditionalize product name and shell prompt by @product. If the product has a single book, these are defined right in the bookmap. If there is a family of books related to a product, they are defined in a separate map file.

All products release on a planned version and date schedule. These variables are defined in a separate map file, programmatically updated by our release database.

I hope you are looking at making this element structure more user-friendly:

  <keydef keys="Prompt" product="all">
    <topicmeta>
      <keywords>
        <keyword>this_shell</keyword>
      </keywords>
    </topicmeta>
  </keydef>
  <keydef keys="Prompt" product="prod1">
    <topicmeta>
      <keywords>
        <keyword>prod1_shell</keyword>
      </keywords>
    </topicmeta>
  </keydef>
...


This gets lengthy when defining many values -- or many conditional values!

 - Chris


Patricia Billard
 

Hi Kris, 
Most of our group uses SDL variables instead of keys, but I wanted to respond to your other questions. 
  • We use variable text for the company name (full and abbreviated), product names, URLs, names of websites, software version numbers, publication titles or shortened names, different hardware parts or software components that have changed names in the past, UI window names, and UI button or menu item names - especially when those names are changing often (usually when a product is first being developed).  
  • By far the biggest pain point is that <ph> can't be used in several places in which we'd like to use a variable such as <uicontrol>, <wintitle>, <userinput>, <msgblock><organization>, and so forth. That is a huge pain, because we have to define multiple variable names for the same thing, and we can't offer a single Schematron quick fix to replace a text company name with the correct variable, for example.  
Thank you,
--Trish Billard


Kristen James Eberlein
 

Hi, Chris.

A question: Do you maintain two versions of the product name (one with one trademarks, one without) so that only the first instance in a topic is rendered with a trademark? I've seen some companies add logic about applying trademark symbols to their transformation logic.

Re making the markup more "user-friendly," below is what we are currently considering:

  <keydef keys="product-name">
    <topicmeta>
      <keytext>My Wonderful Product</keytext>
    </topicmeta>
  </keydef>
Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
OASIS Distinguished Contributor
Principal consultant, Eberlein Consulting LLC
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)

On 10/27/2020 9:38 AM, Chris Papademetrious wrote:
Hi Kris,

We use variables for

  • Product name
  • Product name, trademarked version
  • Product release version
  • Product release date
  • Product shell prompt (a software thing)

Some of our books are conditional across multiple products, and so we conditionalize product name and shell prompt by @product. If the product has a single book, these are defined right in the bookmap. If there is a family of books related to a product, they are defined in a separate map file.

All products release on a planned version and date schedule. These variables are defined in a separate map file, programmatically updated by our release database.

I hope you are looking at making this element structure more user-friendly:

  <keydef keys="Prompt" product="all">
    <topicmeta>
      <keywords>
        <keyword>this_shell</keyword>
      </keywords>
    </topicmeta>
  </keydef>
  <keydef keys="Prompt" product="prod1">
    <topicmeta>
      <keywords>
        <keyword>prod1_shell</keyword>
      </keywords>
    </topicmeta>
  </keydef>
...


This gets lengthy when defining many values -- or many conditional values!

 - Chris


Kristen James Eberlein
 

Hi, Trish.

Thanks for chiming in.

A recommendation for you: the <text> element is available in <uicontrol>, <wintitle>, <userinput>, and <msgblock>. Have you considered using <text> to hold your variable text? Let me know.

The <text> element was introduced in DITA 1.2, and so some implementation that predate 2010 might not use <text>. The <text> element is available just about everywhere!

The <ph> element allows just about EVERYTHING in its content model, so it's unlikely that the TC would add it to the content model of the elements that you mention. Also, <wintitle> is specialized from <keyword>, so it really cannot contain <ph>.

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
OASIS Distinguished Contributor
Principal consultant, Eberlein Consulting LLC
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)

On 10/27/2020 11:25 AM, Patricia Billard wrote:
Hi Kris, 
Most of our group uses SDL variables instead of keys, but I wanted to respond to your other questions. 
  • We use variable text for the company name (full and abbreviated), product names, URLs, names of websites, software version numbers, publication titles or shortened names, different hardware parts or software components that have changed names in the past, UI window names, and UI button or menu item names - especially when those names are changing often (usually when a product is first being developed).  
  • By far the biggest pain point is that <ph> can't be used in several places in which we'd like to use a variable such as <uicontrol>, <wintitle>, <userinput>, <msgblock><organization>, and so forth. That is a huge pain, because we have to define multiple variable names for the same thing, and we can't offer a single Schematron quick fix to replace a text company name with the correct variable, for example.  
Thank you,
--Trish Billard


Wito Zoerkler
 

Hi Kris,

Some feedback from my side:
  • The keyword mechanism at present is a very clunky way to define a variable. <keydef keys="KEY"><topicmeta><keywords><keyword>… It’s not at all intuitive and should be much simpler to define a keyword. But the current keyword reference concept is good.
  • Only a few element types are allowed in the keyword so that limits its potential usefulness. Fortunately you can have tm there so it can be used for product names. As we use keywords as well for parameters and parameter values we miss certain element types in the keyword, e.g. <sub>. Our alternative is a 'variables topic'  and there you can have <ph> elements which are then used with conkeyref.
Best regards
Wito


Kristen James Eberlein
 

I think you'll be pleased with the design that the DITA TC is currently considering. The markup for a key definition is as follows:

  <keydef keys="product-name">
    <topicmeta>
      <keytext>My Wonderful Product<sup>2</sup></keytext>
    </topicmeta>
  </keydef>

The current plan for the <keytext> element to have the following content model:
  • <cite>
  • <keyword>
  • <q>
  • <term>
  • <text>
  • <keyword>
Because the content model will permit <keyword> and <ph>, almost all the element defined in the various domains (including highlighting: <sub>, <sub>) will be permitted in the content model.

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
OASIS Distinguished Contributor
Principal consultant, Eberlein Consulting LLC
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)

On 10/28/2020 8:42 AM, Wito Zoerkler wrote:
Hi Kris,

Some feedback from my side:
  • The keyword mechanism at present is a very clunky way to define a variable. <keydef keys="KEY"><topicmeta><keywords><keyword>… It’s not at all intuitive and should be much simpler to define a keyword. But the current keyword reference concept is good.
  • Only a few element types are allowed in the keyword so that limits its potential usefulness. Fortunately you can have tm there so it can be used for product names. As we use keywords as well for parameters and parameter values we miss certain element types in the keyword, e.g. <sub>. Our alternative is a 'variables topic'  and there you can have <ph> elements which are then used with conkeyref.
Best regards
Wito


Jonathan Hanna
 

Hi Kris,

I currently use variable text for the following:
  • Product Name
  • Product Number
  • Documentation Number
  • Documentation Rev
I use the standard keydef > topicmeta > keywords > keyword markup to create variable text. Like others, I find this structure cumbersome. However, it has not been a huge issue since I use a template map I created in Oxygen that already has these keydefs included. For key referencing, I typically just use the keyword element inline.

Regards,
Jonathan


Shane Taylor
 

Hi, Kris—

We use keys for text for the following:
  • Product names 
  • Feature names
  • Hardware and operating system names
  • Learning management system names
  • Company names
  • Other copyrighted terms
We define these in dedicated maps. These maps are used not only per deliverable but also in branch processing contexts, where we gain a lot of reuse efficiency by building, for example, topics supporting 5 learning platforms × 6 LMSs.

I second the feedback both about the ability to use these keys in more text contexts and simplifying the declarative markup
  • To expand the reuse contexts, consider allowing keyref reuse via other elements such as <text> or <tm>.
  • To simplify the markup, I like the <keytext> approach to standardize this, since there are now multiple elements/attributes you can use that each have different priorities and implementation. Additionally, could we:
    • disallow specifying an @href
    • include <keytext>—if necessary, in a new parent like <keytextdef>— without the intervening <topicmeta>

 


Kristen James Eberlein
 

Hi, Shane. A couple of points:

  • Disallowing an @href is not an option. A lost of implementations use keys to reference images, and in such scenarios, the alternate text for the image is provided by the variable text. For example, using current DITA 1.3 markup:

        <keydef keys="company-logo" href="images/eberlein-consulting-logo.png">
          <topicmeta>
            <keywords>
              <keyword>Logo for Eberlein Consulting LLCS</keyword>
            </keywords>
          </topicmeta>
        </keydef>


  • What is your use case for "including <keytext>—if necessary, in a new parent like <keytextdef>— without the intervening <topicmeta>"?
Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
OASIS Distinguished Contributor
Principal consultant, Eberlein Consulting LLC
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)

On 10/28/2020 12:08 PM, Shane Taylor wrote:
  • To simplify the markup, I like the <keytext> approach to standardize this, since there are now multiple elements/attributes you can use that each have different priorities and implementation. Additionally, could we:
    • disallow specifying an @href
    • include <keytext>—if necessary, in a new parent like <keytextdef>— without the intervening <topicmeta>


    Shane Taylor
     

    Definitely not asking to disallow @href for all keys, just text-only ones.

    The use case for eliminating the intervening <topicmeta> is nothing more than simplifying the markup. It's never seemed a useful tag, and less so when defining text-only keys when no other content should be provided but the text for the key.

    As it stands today, the flexibility of key definition markup allows authors to do a lot of things that make no sense semantically and won't work. Onboarding new writers would be aided by markup that enforced valid use cases and disallowed malarkey ;-).

    Shane Taylor


    On Wed, Oct 28, 2020 at 12:36 PM Kristen James Eberlein <kris@...> wrote:

    Hi, Shane. A couple of points:

    • Disallowing an @href is not an option. A lost of implementations use keys to reference images, and in such scenarios, the alternate text for the image is provided by the variable text. For example, using current DITA 1.3 markup:

          <keydef keys="company-logo" href="images/eberlein-consulting-logo.png">
            <topicmeta>
              <keywords>
                <keyword>Logo for Eberlein Consulting LLCS</keyword>
              </keywords>
            </topicmeta>
          </keydef>


    • What is your use case for "including <keytext>—if necessary, in a new parent like <keytextdef>— without the intervening <topicmeta>"?
    Best,
    Kris

    Kristen James Eberlein
    Chair, OASIS DITA Technical Committee
    OASIS Distinguished Contributor
    Principal consultant, Eberlein Consulting LLC
    www.eberleinconsulting.com
    +1 919 622-1501; kriseberlein (skype)

    On 10/28/2020 12:08 PM, Shane Taylor wrote:
    • To simplify the markup, I like the <keytext> approach to standardize this, since there are now multiple elements/attributes you can use that each have different priorities and implementation. Additionally, could we:
    • disallow specifying an @href
    • include <keytext>—if necessary, in a new parent like <keytextdef>— without the intervening <topicmeta>


    Kristen James Eberlein
     

    Hi, Shane.

    You might want to specialize to create the particular key-definition elements that you want for your writers. Or could you institute guardrails by implementing constraints or hiddening certain elements from authors? Establish best patterns for key definitions through authoring templates?

    I'd be curious to see the types of anti-patterns ("malarkey") that you have seen authors try. Willing to share some?

    There are limitations to the numbers and kinds of elements that we introduce into the actual body of DITA. We need to be cognizant of the element count and make sure that what we introduce has a really wide utility for the community of DITA users.

    Best,
    Kris

    Kristen James Eberlein
    Chair, OASIS DITA Technical Committee
    OASIS Distinguished Contributor
    Principal consultant, Eberlein Consulting LLC
    www.eberleinconsulting.com
    +1 919 622-1501; kriseberlein (skype)

    On 10/28/2020 5:30 PM, Shane Taylor wrote:
    Definitely not asking to disallow @href for all keys, just text-only ones.

    The use case for eliminating the intervening <topicmeta> is nothing more than simplifying the markup. It's never seemed a useful tag, and less so when defining text-only keys when no other content should be provided but the text for the key.

    As it stands today, the flexibility of key definition markup allows authors to do a lot of things that make no sense semantically and won't work. Onboarding new writers would be aided by markup that enforced valid use cases and disallowed malarkey ;-).

    Shane Taylor


    On Wed, Oct 28, 2020 at 12:36 PM Kristen James Eberlein <kris@...> wrote:

    Hi, Shane. A couple of points:

    • Disallowing an @href is not an option. A lost of implementations use keys to reference images, and in such scenarios, the alternate text for the image is provided by the variable text. For example, using current DITA 1.3 markup:

          <keydef keys="company-logo" href="images/eberlein-consulting-logo.png">
            <topicmeta>
              <keywords>
                <keyword>Logo for Eberlein Consulting LLCS</keyword>
              </keywords>
            </topicmeta>
          </keydef>


    • What is your use case for "including <keytext>—if necessary, in a new parent like <keytextdef>— without the intervening <topicmeta>"?
    Best,
    Kris

    Kristen James Eberlein
    Chair, OASIS DITA Technical Committee
    OASIS Distinguished Contributor
    Principal consultant, Eberlein Consulting LLC
    www.eberleinconsulting.com
    +1 919 622-1501; kriseberlein (skype)

    On 10/28/2020 12:08 PM, Shane Taylor wrote:
    • To simplify the markup, I like the <keytext> approach to standardize this, since there are now multiple elements/attributes you can use that each have different priorities and implementation. Additionally, could we:
    • disallow specifying an @href
    • include <keytext>—if necessary, in a new parent like <keytextdef>— without the intervening <topicmeta>


    Patricia Billard
     

    Hi Kristen,

    Thank you for the suggestion. I'll bring it up to the team.  We had not considered <text>, I think partly because the DITA 1.2 spec did not address variable elements in an obvious way if you weren't using keys.  The spec's suggestion also steered us away from looking at <text> for variables when we did our original migration:  "For contexts where ph is available, authors should use that element. Where keyword is available, authors should use that element. Where neither ph nor keyword is available, text can be used to pull content by conref." We also implemented some nested variables, in which the company name was referenced in the variable defined for the product name, for example.
    The original discussion was a long time ago, but at the time <ph> seemed the best choice for most things, and we had a few other elements we allowed as variables, but I don't think we anticipated needing to use the company name in some of these situations. It might be a solution to use <text> for variables that we don't want to create multiple variable names for the same thing.
    --Trish