Topics

Keyscopes?


Dan Vint
 

How stable or well implemented are they? I'm using DITA OT 3.4.0 and they don't appear to be working as expected. I have 5 separate publications that had their own copy of keymaps that had a common set of variable names. So the name BASE_NAME appears in each keymap but with a different value.

We are now publishing these as one bundle. So they have been grouped together with one map like this.
<map>
<topichead keyscope="DirectoryServerKeys" navtitle="Server Administration Guide">
<mapref format="ditamap" keyref="bbv1564011413207"/>
</topichead>
<topichead keyscope="ProxyServerKeys" navtitle="Proxy Server Administration Guide">
<mapref format="ditamap" keyref="dsa1564011474136"/>
</topichead>
<topichead keyscope="ConsentSolutionKeys" navtitle="Consent Solution Guide">
<mapref format="ditamap" keyref="ugq1564011487101"
navtitle="Consent Solution Guide"/>
</topichead>
<topichead keyscope="DelegatedAdminKeys" navtitle="Delegated Admin Application Guide">
<mapref format="ditamap" keyref="nyx1564012075196"
navtitle="Delegated Admin Guide"/>
</topichead>
<topichead keyscope="DataSyncKeys" navtitle="Administration Guide">
<mapref format="ditamap" keyref="wfk1564011491470"
navtitle="Administration Guide"/>
</topichead>
</map>

There is no keymap above any of the maprefs, yet BASE_NAME in all the sections shows the same value. For testing I commented out the definition that was being used everywhere and one of the other definitions replaced it.

This content is huge and ugly. I may try building my own sample and testing with it in case I'm not finding the real problem in this content and thinking it is the keyscope that is not working.

..dan


Radu Coravu
 

Hi Dan,

Maybe indeed you can construct a small DITA project exemplifying your case, then try to publish it to plain HTML5 using the latest DITA OT distribution. If that does not work, maybe you can share the small DITA project with us along with details about the expected output.

Regards,
Radu

Radu Coravu
Oxygen XML Editor

On 8/6/20 2:23 AM, Dan Vint wrote:
How stable or well implemented are they? I'm using DITA OT 3.4.0 and they don't appear to be working as expected. I have 5 separate publications that had their own copy of keymaps that had a common set of variable names. So the name BASE_NAME appears in each keymap but with a different value.

We are now publishing these as one bundle. So they have been grouped together with one map like this.
<map>
   <topichead keyscope="DirectoryServerKeys" navtitle="Server Administration Guide">
      <mapref format="ditamap" keyref="bbv1564011413207"/>
   </topichead>
   <topichead keyscope="ProxyServerKeys" navtitle="Proxy Server Administration Guide">
      <mapref format="ditamap" keyref="dsa1564011474136"/>
   </topichead>
   <topichead keyscope="ConsentSolutionKeys" navtitle="Consent Solution Guide">
      <mapref format="ditamap" keyref="ugq1564011487101"
         navtitle="Consent Solution Guide"/>
   </topichead>
   <topichead keyscope="DelegatedAdminKeys" navtitle="Delegated Admin Application Guide">
      <mapref format="ditamap" keyref="nyx1564012075196"
         navtitle="Delegated Admin Guide"/>
   </topichead>
   <topichead keyscope="DataSyncKeys" navtitle="Administration Guide">
      <mapref format="ditamap" keyref="wfk1564011491470"
         navtitle="Administration Guide"/>
   </topichead>
</map>

There is no keymap above any of the maprefs, yet BASE_NAME in all the sections shows the same value. For testing I commented out the definition that was being used everywhere and one of the other definitions replaced it.

This content is huge and ugly. I may try building my own sample and testing with it in case I'm not finding the real problem in this content and thinking it is the keyscope that is not working.

..dan


Lief Erickson
 

Hi Dan--

Here's a mockup of the first three <topichead> elements from your example where I added a <ditavalref> with <dvrResourcePrefix> and <dvrKeyscopePrefix> elements. With these I am able to produce unique output for BASE_NAME. I was using this structure successfully with DITA-OT 2.2.5 (if memory serves) but certainly 2.5.4. I tested this example with DITA-OT 3.4 and 3.5.2 and had successful results. Since you mentioned that BASE_NAME was defined in the separate ditamaps, I went with that. As such, any brave soul copying this would need to also define the key. Further, new ditavals will need to be created. 

<map>
    <topichead keyscope="DirectoryServerKeys" navtitle="Server
        Administration Guide">
        <ditavalref href="DirectoryServerKeys.ditaval">
            <ditavalmeta>
                <dvrResourcePrefix>DirectoryServerKeys-</dvrResourcePrefix>
                <dvrKeyscopePrefix>DirectoryServerKeys-Scope</dvrKeyscopePrefix>
            </ditavalmeta>
        </ditavalref>
        <mapref format="ditamap" keyref="bbv1564011413207"/>
    </topichead>
    <topichead keyscope="ProxyServerKeys" navtitle="Proxy Server
        Administration Guide">
        <ditavalref href="ProxyServerKeys.ditaval">
            <ditavalmeta>
                <dvrResourcePrefix>ProxyServerKeys-</dvrResourcePrefix>
                <dvrKeyscopePrefix>ProxyServerKeys-Scope</dvrKeyscopePrefix>
            </ditavalmeta>
        </ditavalref>
        <mapref format="ditamap" keyref="dsa1564011474136"/>
    </topichead>
    <topichead keyscope="ConsentSolutionKeys" navtitle="Consent Solution
        Guide">
        <ditavalref href="ConsentSolutionKeys.ditaval">
            <ditavalmeta>
                <dvrResourcePrefix>ConsentSolutionKeys-</dvrResourcePrefix>
                <dvrKeyscopePrefix>ConsentSolutionKeys-Scope</dvrKeyscopePrefix>
            </ditavalmeta>
        </ditavalref>
        <mapref format="ditamap" keyref="ugq1564011487101"
            navtitle="Consent Solution Guide"/>
    </topichead>
</map>

Example ditaval files. Modify as necessary.

DirectoryServerKeys.ditaval  
<val>
    <prop action="exclude"/>
    <prop action="include" att="product" val=" DirectoryServerKeys"/>
</val>

ProxyServerKeys.ditaval  
<val>
    <prop action="exclude"/>
    <prop action="include" att="product" val="ProxyServerKeys"/>
</val>

In DITA-OT 3.4.1 there was a change related to the <dvrResourcePrefix> or <dvrResourceSuffix> elements that you may want to be aware of.

-Lief

On Wed, Aug 5, 2020 at 6:23 PM Dan Vint <dvint@...> wrote:
How stable or well implemented are they? I'm using DITA OT 3.4.0 and
they don't appear to be working as expected. I have 5 separate
publications that had their own copy of keymaps that had a common set of
variable names. So the name BASE_NAME appears in each keymap but with a
different value.

We are now publishing these as one bundle. So they have been grouped
together with one map like this.
<map>
    <topichead keyscope="DirectoryServerKeys" navtitle="Server
Administration Guide">
       <mapref format="ditamap" keyref="bbv1564011413207"/>
    </topichead>
    <topichead keyscope="ProxyServerKeys" navtitle="Proxy Server
Administration Guide">
       <mapref format="ditamap" keyref="dsa1564011474136"/>
    </topichead>
    <topichead keyscope="ConsentSolutionKeys" navtitle="Consent Solution
Guide">
       <mapref format="ditamap" keyref="ugq1564011487101"
          navtitle="Consent Solution Guide"/>
    </topichead>
    <topichead keyscope="DelegatedAdminKeys" navtitle="Delegated Admin
Application Guide">
       <mapref format="ditamap" keyref="nyx1564012075196"
          navtitle="Delegated Admin Guide"/>
    </topichead>
    <topichead keyscope="DataSyncKeys" navtitle="Administration Guide">
       <mapref format="ditamap" keyref="wfk1564011491470"
          navtitle="Administration Guide"/>
    </topichead>
</map>

There is no keymap above any of the maprefs, yet BASE_NAME in all the
sections shows the same value. For testing I commented out the
definition that was being used everywhere and one of the other
definitions replaced it.

This content is huge and ugly. I may try building my own sample and
testing with it in case I'm not finding the real problem in this content
and thinking it is the keyscope that is not working.

..dan




Dan Vint
 

Thanks for the info. 1.3 appears to make this much simpler although I was checking Google to see if there was something more needed than just adding this keyscope label.



Sent from my Verizon, Samsung Galaxy smartphone


-------- Original message --------
From: Lief Erickson <lief.erickson@...>
Date: 8/5/20 10:34 PM (GMT-08:00)
To: main@dita-users.groups.io
Cc: DITA Users <dita-users@groups.io>
Subject: Re: [dita-users] Keyscopes?

Hi Dan--

Here's a mockup of the first three <topichead> elements from your example where I added a <ditavalref> with <dvrResourcePrefix> and <dvrKeyscopePrefix> elements. With these I am able to produce unique output for BASE_NAME. I was using this structure successfully with DITA-OT 2.2.5 (if memory serves) but certainly 2.5.4. I tested this example with DITA-OT 3.4 and 3.5.2 and had successful results. Since you mentioned that BASE_NAME was defined in the separate ditamaps, I went with that. As such, any brave soul copying this would need to also define the key. Further, new ditavals will need to be created. 

<map>
    <topichead keyscope="DirectoryServerKeys" navtitle="Server
        Administration Guide">
        <ditavalref href="DirectoryServerKeys.ditaval">
            <ditavalmeta>
                <dvrResourcePrefix>DirectoryServerKeys-</dvrResourcePrefix>
                <dvrKeyscopePrefix>DirectoryServerKeys-Scope</dvrKeyscopePrefix>
            </ditavalmeta>
        </ditavalref>
        <mapref format="ditamap" keyref="bbv1564011413207"/>
    </topichead>
    <topichead keyscope="ProxyServerKeys" navtitle="Proxy Server
        Administration Guide">
        <ditavalref href="ProxyServerKeys.ditaval">
            <ditavalmeta>
                <dvrResourcePrefix>ProxyServerKeys-</dvrResourcePrefix>
                <dvrKeyscopePrefix>ProxyServerKeys-Scope</dvrKeyscopePrefix>
            </ditavalmeta>
        </ditavalref>
        <mapref format="ditamap" keyref="dsa1564011474136"/>
    </topichead>
    <topichead keyscope="ConsentSolutionKeys" navtitle="Consent Solution
        Guide">
        <ditavalref href="ConsentSolutionKeys.ditaval">
            <ditavalmeta>
                <dvrResourcePrefix>ConsentSolutionKeys-</dvrResourcePrefix>
                <dvrKeyscopePrefix>ConsentSolutionKeys-Scope</dvrKeyscopePrefix>
            </ditavalmeta>
        </ditavalref>
        <mapref format="ditamap" keyref="ugq1564011487101"
            navtitle="Consent Solution Guide"/>
    </topichead>
</map>

Example ditaval files. Modify as necessary.

DirectoryServerKeys.ditaval  
<val>
    <prop action="exclude"/>
    <prop action="include" att="product" val=" DirectoryServerKeys"/>
</val>

ProxyServerKeys.ditaval  
<val>
    <prop action="exclude"/>
    <prop action="include" att="product" val="ProxyServerKeys"/>
</val>

In DITA-OT 3.4.1 there was a change related to the <dvrResourcePrefix> or <dvrResourceSuffix> elements that you may want to be aware of.

-Lief

On Wed, Aug 5, 2020 at 6:23 PM Dan Vint <dvint@...> wrote:
How stable or well implemented are they? I'm using DITA OT 3.4.0 and
they don't appear to be working as expected. I have 5 separate
publications that had their own copy of keymaps that had a common set of
variable names. So the name BASE_NAME appears in each keymap but with a
different value.

We are now publishing these as one bundle. So they have been grouped
together with one map like this.
<map>
    <topichead keyscope="DirectoryServerKeys" navtitle="Server
Administration Guide">
       <mapref format="ditamap" keyref="bbv1564011413207"/>
    </topichead>
    <topichead keyscope="ProxyServerKeys" navtitle="Proxy Server
Administration Guide">
       <mapref format="ditamap" keyref="dsa1564011474136"/>
    </topichead>
    <topichead keyscope="ConsentSolutionKeys" navtitle="Consent Solution
Guide">
       <mapref format="ditamap" keyref="ugq1564011487101"
          navtitle="Consent Solution Guide"/>
    </topichead>
    <topichead keyscope="DelegatedAdminKeys" navtitle="Delegated Admin
Application Guide">
       <mapref format="ditamap" keyref="nyx1564012075196"
          navtitle="Delegated Admin Guide"/>
    </topichead>
    <topichead keyscope="DataSyncKeys" navtitle="Administration Guide">
       <mapref format="ditamap" keyref="wfk1564011491470"
          navtitle="Administration Guide"/>
    </topichead>
</map>

There is no keymap above any of the maprefs, yet BASE_NAME in all the
sections shows the same value. For testing I commented out the
definition that was being used everywhere and one of the other
definitions replaced it.

This content is huge and ugly. I may try building my own sample and
testing with it in case I'm not finding the real problem in this content
and thinking it is the keyscope that is not working.

..dan




Dan Vint
 

My test sample worked. I must be missing something in the content that is causing the problem. I'm going to tease apart the actual content some more as I must be missing some small detail.



Sent from my Verizon, Samsung Galaxy smartphone


-------- Original message --------
From: Radu Coravu <radu_coravu@...>
Date: 8/5/20 10:13 PM (GMT-08:00)
To: main@dita-users.groups.io, dita-users@groups.io
Subject: Re: [dita-users] Keyscopes?

Hi Dan,

Maybe indeed you can construct a small DITA project exemplifying your
case, then try to publish it to plain HTML5 using the latest DITA OT
distribution. If that does not work, maybe you can share the small DITA
project with us along with details about the expected output.

Regards,
Radu

Radu Coravu
Oxygen XML Editor

On 8/6/20 2:23 AM, Dan Vint wrote:
> How stable or well implemented are they? I'm using DITA OT 3.4.0 and
> they don't appear to be working as expected. I have 5 separate
> publications that had their own copy of keymaps that had a common set
> of variable names. So the name BASE_NAME appears in each keymap but
> with a different value.
>
> We are now publishing these as one bundle. So they have been grouped
> together with one map like this.
> <map>
>    <topichead keyscope="DirectoryServerKeys" navtitle="Server
> Administration Guide">
>       <mapref format="ditamap" keyref="bbv1564011413207"/>
>    </topichead>
>    <topichead keyscope="ProxyServerKeys" navtitle="Proxy Server
> Administration Guide">
>       <mapref format="ditamap" keyref="dsa1564011474136"/>
>    </topichead>
>    <topichead keyscope="ConsentSolutionKeys" navtitle="Consent
> Solution Guide">
>       <mapref format="ditamap" keyref="ugq1564011487101"
>          navtitle="Consent Solution Guide"/>
>    </topichead>
>    <topichead keyscope="DelegatedAdminKeys" navtitle="Delegated Admin
> Application Guide">
>       <mapref format="ditamap" keyref="nyx1564012075196"
>          navtitle="Delegated Admin Guide"/>
>    </topichead>
>    <topichead keyscope="DataSyncKeys" navtitle="Administration Guide">
>       <mapref format="ditamap" keyref="wfk1564011491470"
>          navtitle="Administration Guide"/>
>    </topichead>
> </map>
>
> There is no keymap above any of the maprefs, yet BASE_NAME in all the
> sections shows the same value. For testing I commented out the
> definition that was being used everywhere and one of the other
> definitions replaced it.
>
> This content is huge and ugly. I may try building my own sample and
> testing with it in case I'm not finding the real problem in this
> content and thinking it is the keyscope that is not working.
>
> ..dan
>
>
>





Thomas Rathkamp
 

What would do within a topic, though? Instead of applying an attribute within that file, would you repeat that DITAVal string in each instance? That appears to be more work. 


On Aug 8, 2020, at 6:04 PM, Chris Papademetrious <chrispitude@...> wrote:

Hi all,

I feel like it would be useful to be able to include DITAVAL directives inline in the map, instead of in files:

<map>
    <topichead keyscope="NoviceSection" navtitle="Novice Documentation">
        <ditaval>
            <prop att="audience" val="novice" action="include"/>
            <prop att="audience" val="expert" action="exclude"/>
            <dvrResourcePrefix>Novice-</dvrResourcePrefix>
            <dvrKeyscopePrefix>Novice-Scope</dvrKeyscopePrefix>
        </ditaval>
        <mapref format="ditamap" keyref="..."/>
    </topichead>

My thinking is,

  • This allows the branch filtering intent to be visible *and* editable directly where the content is instantiated, instead of requiring side files.
  • DITAVAL used for branch filtering is likely to be single-variable and simple (2-3 directives).

Thoughts?

 - Chris