Date   

Key definitions for variable text: Conditional processing

Kristen James Eberlein
 

Hi, dita-users community.

I have another question about variable text defined by keys. (Variable text is is text that you want to appear differently based on the context.)

For implementations that use keys to define variable text:

  1. How do you handle conditional processing of the key definitions?
  2. What markup are you currently using for this?

Again, for DITA 2.0, the DITA TC is introducing simplified markup and processing for variable content referenced using keys. I am soliciting background information that will help us ensure that we are covering relevant use cases in the best way.

--
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)



[ann][webinar] Introducing the Oxygen Publishing Engine for DITA #Oxygen

alin_belu@...
 

Hello, 
 
Next Wednesday, on November 4, you are invited to our latest live event - “Introducing the Oxygen Publishing Engine for DITA” webinar! 
 
Have you been looking for a solution that offers support for transforming your DITA content into PDF and WebHelp output? Look no further! 
 
In this webinar, Julien Lacour, software developer at Syncro Soft, will introduce you to the Oxygen Publishing Engine – an automation product that bundles the DITA Open toolkit transformation engine with Oxygen publishing plugins and the PDF Chemistry engine. 
 
This event will represent a crash-course for you to learn what the Oxygen Publishing Engine is by showing you how to install it, configure it in a Continuous Integration system, and then customize your output. 
 
You will be shown its components, various workflows, and also get the chance to see how to transform a DITA map document by learning how to: 
* Use the “DITA Map PDF – based on HTML5 & CSS” transformation on an integration server using a publishing template for customizing the output. 
* Create a custom CSS stylesheet and use it in your transformation to get that extra level of customization for your specific needs. 
* Debug the CSS inside both a web browser and Oxygen to see how to choose the correct selectors and properties used for further styling your content. 
 
This is a free event and you can register at http://www.oxygenxml.com/evs2020-15.html 
 
Make sure to check the full list of our upcoming Events: https://www.oxygenxml.com/events_programme.html 
 
Best regards,
Alin
--
Alin Belu
Oxygen XML Editor


[ann][webinar] Navigating Tech Comm with Geoffrey Chaucer with Brigid Brockway #tcdojo free 2 Nov @ 9AM PT

Liz Fraley
 

Title: Navigating Tech Comm with Geoffrey Chaucer

When: Monday, 2 Nov, 9:00 AM - 9:30 AM PT

Register: http://bit.ly/tcdojo-202011-brockway

Description:

Most people know Geoffrey Chaucer as the author of The Canterbury Tales, a group of stories so naughty that schoolbooks still censor them now, over 600 years later. Many are surprised to learn that Geoffrey Chaucer also wrote one of the oldest surviving technical documents written in the English language.

More surprising still is the fact that this document, A Treatise on the Astrolabe, remains an example of excellent technical writing even by today’s standards. An astrolabe is an ancient instrument that helped astronomers study the stars, surveyors study the land, and sailors study the sea. In this session we’ll use Chaucer and his astrolabe to study the timeless elements of great technical communication.

Attendees will view advanced writing and editing skills through an ancient lens and emerge ready to produce concrete, concise, and cutting-edge documentation that’s just right for their audience.

About the Visiting TC Dojo Master:

Brigid Brockway worked as a technical writer for DRB Systems, an industry leader in car care solutions, for nearly fifteen years. She has a BA in English from Ursuline College and a Masters of Fine Arts in Creative Writing: Nonfiction from Ashland University. Her work has been featured on National Public Radio and in “Every Pigeon” literary magazine.


-:-

The TC Dojo is brought to you by Single-Sourcing Solutions. At the TC Dojo, you pick the topics and we find the experts. Learn more: http://webinar.tcdojo.org


Register: http://bit.ly/tcdojo-202011-brockway


Re: Variable text referenced using keys

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>


Re: Glossary term: singular vs. plural #glossary

Wito Zoerkler
 

Hi, Joe,

thanks for your feedback.
I also don't mind if the glossary term in the glossary is in the singular and is used in the plural in the text.
My question was more about what is the best technical solution for this.
Example:
  • 'software module' is defined in a glossary topic (singular). The output can be different depending on the format (e.g. glossary chapter in PDF, mouse hover)
  • By default, glossary words are inserted into the text as follows: <abbreviated-form keyref="KEYNAME"/> or <term keyref="KEYNAME">, i.e. they would then appear as a singular in the text.
The question is, how can I use the glossary term in the text in the plural?
<term keyref="KEYNAME">software modules</term> is just an idea. The question is whether it is a good idea? Does anyone have any experience with this? It won't work with <abbreviated-form> because the content model doesn't allow any element or text (which makes sense because either the <glossSurfaceForm> or <glossAcronym> is rendered in the output).

Any idea how to deal with it best?

Best
Wito


Re: Con(key)reffing terms: uppercase - lowercase

Joe Russo
 

Thanks Jang! Silly mistake on my part. As an avid cyclist, who hasn't been to either, I hope to make it to both some day!


Re: Glossary term: singular vs. plural #glossary

Joe Russo
 

So are you thinking of something like:
<p>Instead of writing monolithic code, you can use <term keyref="KEYNAME">software modules</term> to make your programs more agile.</p>

And then a pop-up that would say something like:
A software module is a block of code that can be reused.

This mix of singular and plural doesn't bother me at all.


Re: Variable text referenced using keys

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>


Re: Variable text referenced using keys

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>


    Re: Randomizing Child Nodes of a Parent

    Westley W.
     

    George,

    This works wonderful.  I didn't expect anyone to provide a script, I can't thank you enough.  I'm pretty green when it comes to XSLT, however, I was able to implement this as a Refactoring option easily as you said.

    I ran into one issue where a DITA file could have multiple <ul> elements with same number of <li> elements which results in the same order generated. A little bit of searching lead me to this StackOverflow post where I modified the code as such:
    ...
    <xsl:variable name="random" select="random-number-generator()"/>
    <xsl:variable name="dummy" select="generate-id()"/>
    <xsl:copy>
    <xsl:apply-templates select="@*"/>
    <xsl:variable name="n" select="count(li)"/>
    <xsl:variable name="perm" select="random-number-generator($dummy)?permute(1 to $n)"/>
    ....

    As the post suggested, it's probably not proper but it resolved the few DITA files that did have this issue. 

    Thanks again, George! 


    Re: Variable text referenced using keys

    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>

     


    Re: Variable text referenced using keys

    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


    Re: Variable text referenced using keys

    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


    Re: Variable text referenced using keys

    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


    Re: Randomizing Child Nodes of a Parent

    George Cristian Bina
     

    Hello,

    If XSLT 3 is an option, then you may use something like the stylesheet below (this can be easily set also as a refactoring action in oXygen, if you use it, the advantage being that it will keep the rest of your document as it is, DOCTYPE declaration, etc.):

    <?xml version="1.0" encoding="UTF-8"?>
    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    exclude-result-prefixes="xs"
    version="3.0">

    <xsl:template match="node() | @*">
    <xsl:copy>
    <xsl:apply-templates select="node() | @*"/>
    </xsl:copy>
    </xsl:template>

    <xsl:template match="ul">
    <xsl:variable name="random" select="random-number-generator()"/>
    <xsl:copy>
    <xsl:apply-templates select="@*"/>
    <xsl:variable name="n" select="count(li)"/>
    <xsl:variable name="perm" select="random-number-generator()?permute(1 to $n)"/>
    <xsl:message select="$perm"></xsl:message>
    <xsl:for-each select="node()">
    <xsl:choose>
    <xsl:when test="self::li">
    <xsl:variable name="index" select="count(preceding-sibling::li) + 1"/>
    <xsl:apply-templates select="../li[$perm[$index]]"/>
    </xsl:when>
    <xsl:otherwise>
    <xsl:apply-templates select="."/>
    </xsl:otherwise>
    </xsl:choose>
    </xsl:for-each>
    </xsl:copy>
    </xsl:template>
    </xsl:stylesheet>

    Best Regards,
    George
    --
    George Cristian Bina
    <oXygen/> XML Editor, Schema Editor and XSLT Editor/Debugger
    http://www.oxygenxml.com

    On 10/28/20 12:24 AM, Westley W. wrote:
    Hey everyone,
    I have a situation where I have hundreds of DITA files that contain <ul> elements that contain any number of child <li> elements which need to be randomized. As an example:
    <ul>
    <li>List Item 1</li>
    <li>List Item 2</li>
    <li>List Item 3</li>
    </ul>
    Becomes randomized, one possible outcome:
    <ul>
    <li>List Item 2</li>
    <li>List Item 3</li>
    <li>List Item 1</li>
    </ul>
    I was curious what your best approach would be to randomize the order of these <li> elements for each DITA file? I am attempting to achieve this through a Powershell script with some RegEx but am burning myself out. Another thought I had was utilizing XML Refactoring but I'm not perceiving any logic that could work with XSLT or XQuery.  I feel like there should be an easy solution.
    Thanks,
    Westley


    Re: Variable text referenced using keys

    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


    Re: Variable text referenced using keys

    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


    Randomizing Child Nodes of a Parent

    Westley W.
     

    Hey everyone,

    I have a situation where I have hundreds of DITA files that contain <ul> elements that contain any number of child <li> elements which need to be randomized. As an example:

    <ul>
    <li>List Item 1</li>
    <li>List Item 2</li>
    <li>List Item 3</li>
    </ul>

    Becomes randomized, one possible outcome:

    <ul>
    <li>List Item 2</li>
    <li>List Item 3</li>
    <li>List Item 1</li>
    </ul>

    I was curious what your best approach would be to randomize the order of these <li> elements for each DITA file? I am attempting to achieve this through a Powershell script with some RegEx but am burning myself out. Another thought I had was utilizing XML Refactoring but I'm not perceiving any logic that could work with XSLT or XQuery.  I feel like there should be an easy solution.  

    Thanks,

    Westley


    Glossary term: singular vs. plural #glossary

    Wito Zoerkler
     

    How do you deal with the following use case? What is your solution?
     
    A glossary term is normally defined in singular, e.g. 'software module'. In the context the term is used often as well in plural.
    Ideas I am not really satisfied with:
    • Glossary term defined in plural
    • <term keyref="KEYNAME"/>s  --> Definitely problems with localization
    • <term keyref="KEYNAME">software modules</term>  --> Problems with localization? And this only works with <term> not with <abbreviated-form>
    Best regards
    Wito


    Re: Variable text referenced using keys

    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