Topics

conref and filtering


Stuart Norton
 

Dear DITA folks,

 

Our team has run into a behavior that we found surprising and it looks like it is going to cause us big headaches. It seems that if you use a conref, and the conref includes filtered material (@props), the filters are ignored.  It looks like the ditaval filtering stage happens before conrefs are included, so any filters in the conrefs are ignored…?

 

Does anyone using conref and ditaval filtering have some suggestions about how we can more effectively use conrefs that contain filtered material?

 

I'm attaching a zip with some sample files that demonstrate the issue:

  • map.dita includes concept.dita and filter.ditaval
  • filter.ditaval hides all products other than product = "shown-product"
  • concept.dita conrefs a section in snippets.dita
  • both concept.dita and the conrefed section contain a paragraph with product = "hidden-product"
  • in concept.dita, the paragraph is hidden; in the conrefed section it is shown.

Our expectation was that both concept.dita and the conrefed section would have the same content shown and hidden.

 

Thanks in advance for your advice!

 

Stuart

 


Juniper Business Use Only


stinakab
 

Hi Stuart,

First of all, I would say that since the conref element only references that section (the section is not in the topic for real), it is not possible for the transformation to identify which parts should be filtered or not, especially if that section has no product attribute.
So maybe you could try the following:
For referencing, create product-related sections, not one section that contains only product-related <p> elements.
Example:
<section id="section_amd_sfj_znb" product="shown-product hidden-product">
   <title>Shared section</title>
   <p product="shown-product">I want to show this paragraph</p>
   <p product="hidden-product">I want to hide this paragraph</p>
  </section>
It worked for me to conref this product-related section. If this doesn't work for you, you could also add a product attribute to the conref element, just in case. Our ditaval files are just like yours.

Best,
Christina


Stuart Norton
 

Thanks for your response Christine. I tried it but that's not working for me; whether I used the product attribute in the conref or the section itself, the content inside the conref is not filtered.

 

I also tried setting filter-stage = "late" but I was surprised to see that it had no effect in the content inside the conref was still not filtered (using a modified oxygen DITA OT HTML 5 transform).

 

What worked better was specifying the filter file on the DITA command line using args.filter, instead of inside the map. If I specify args.fiter to indicate the DITA valve file from the command line, instead of using a ditavalref from inside the map, it works as I expected: the material inside the conref with the unmatched product attribute is filtered out, even if I only specify the product attribute on the paragraphs and not the section or topic.

 

Of course, specifying one filter on the command line doesn't help us do with branch filtering, where we want different sections of the ditamap to be filtered differently.

 

It basically looks to me like branch filtering is not designed to handle conditions inside conrefs. Am I missing something?

 

Stuart

 

 

Juniper Business Use Only

From: main@dita-users.groups.io <main@dita-users.groups.io> On Behalf Of stinakab via groups.io
Sent: Tuesday, December 15, 2020 1:30 AM
To: main@dita-users.groups.io
Subject: Re: [dita-users] conref and filtering

 

[External Email. Be cautious of content]

 

Hi Stuart,

First of all, I would say that since the conref element only references that section (the section is not in the topic for real), it is not possible for the transformation to identify which parts should be filtered or not, especially if that section has no product attribute.
So maybe you could try the following:
For referencing, create product-related sections, not one section that contains only product-related <p> elements.
Example:
<section id="section_amd_sfj_znb" product="shown-product hidden-product">
   <title>Shared section</title>
   <p product="shown-product">I want to show this paragraph</p>
   <p product="hidden-product">I want to hide this paragraph</p>
  </section>
It worked for me to conref this product-related section. If this doesn't work for you, you could also add a product attribute to the conref element, just in case. Our ditaval files are just like yours.

Best,
Christina


r.roggen
 

Branch filtering occurs in a different pre-processing stage than the args.filter-based processing. That may explain some of the discrepancies you'll see. When I'm tackling an issue with filters and conrefs or conkeyrefs myself, I usually go back and read these:


I've run into challenges like yours, and usually the solution (not ideal, but a solution) was to find a way to profile the source element rather than an element within the target. In your example, that might mean including <section> in the source topic and conref'ing in the <p> elements instead. There are many ways to address this, though, depending on your authoring environment and your reuse requirements.

Reece


Stuart Norton
 

Reece, thanks for sharing these links – sorry my Google-fu failed me, these are very helpful.

 

Stuart

 

 

Juniper Business Use Only

From: main@dita-users.groups.io <main@dita-users.groups.io> On Behalf Of r.roggen
Sent: Monday, December 21, 2020 7:54 AM
To: main@dita-users.groups.io
Subject: Re: [dita-users] conref and filtering

 

[External Email. Be cautious of content]

 

Branch filtering occurs in a different pre-processing stage than the args.filter-based processing. That may explain some of the discrepancies you'll see. When I'm tackling an issue with filters and conrefs or conkeyrefs myself, I usually go back and read these:


I've run into challenges like yours, and usually the solution (not ideal, but a solution) was to find a way to profile the source element rather than an element within the target. In your example, that might mean including <section> in the source topic and conref'ing in the <p> elements instead. There are many ways to address this, though, depending on your authoring environment and your reuse requirements.

Reece

Reece, thanks for sharing these links –


Shane Taylor
 

If you haven't tried this already, I've found that one solution to resolving conrefs differently in branch processing is to use conkeyref and define the conref source file key in the branch. There are some branch filtering gotchas, so we have set a few best practices that help us avoid them:
  1. Set a keyscope on the branch.
  2. Set the branch processing-role to resource-only.
  3. Define both a different resource and keyscope suffix (or prefix) for each branch condition.
  4. Include a "null" ditavalref to ensure the base/unfiltered topics are not output.
  5. Define keys for every topic in the branch.
  6. Include symbols topics from which you want to conref in the branch.
  7. Use conkeyref to conref the filtered elements.
  8. Include the topics you want to output—and typically to create the TOC for—via keyref.
For example:

    <topicref href="lms-integration.dita" keys="lms-integration" keyscope="lms" processing-role="resource-only">
        <ditavalref href="filters/lms/blackboard.ditaval">
            <ditavalmeta>
                <navtitle>Blackboard</navtitle>
                <dvrResourceSuffix>-bb</dvrResourceSuffix>
                <dvrKeyscopeSuffix>-bb</dvrKeyscopeSuffix>
            </ditavalmeta>
        </ditavalref>
        <ditavalref href="filters/lms/canvas.ditaval">
            <ditavalmeta>
                <navtitle>Canvas</navtitle>
                <dvrResourceSuffix>-canvas</dvrResourceSuffix>
                <dvrKeyscopeSuffix>-canvas</dvrKeyscopeSuffix>
            </ditavalmeta>
        </ditavalref>
        <ditavalref href="filters/lms/brightspace.ditaval">
            <ditavalmeta>
                <navtitle>Brightspace</navtitle>
                <dvrResourceSuffix>-brightspace</dvrResourceSuffix>
                <dvrKeyscopeSuffix>-brightspace</dvrKeyscopeSuffix>
            </ditavalmeta>
        </ditavalref>
        <!-- etc -->
        <ditavalref><!-- null --></ditavalref>

        <mapref href="symbols-lms.ditamap"><!-- LMS names --></mapref>
        <topicref href="symbols-lms.dita" processing-role="resource-only" keys="symbols-lms"/>
        <topicref href="lms-create-or-link-a-course.dita" keys="create-or-link-a-course">
            <topicref href="lms-create-new-course.dita" keys="create-new-mt-course"/>
            <topicref href="lms-copy-course.dita" keys="lms-copy-course"/>
            <topicref href="lms-link-to-an-existing-course.dita" keys="link-to-an-existing-course"/>
        </topicref>
        <!-- etc -->
    </topicref>
   
    <topicref keyref="lms-bb.create-or-link-a-course">
        <topicref keyref="lms-bb.create-new-mt-course"/>
        <!-- etc -->
    </topicref>

   
Replace your conref with:
    <section conkeyref="symbols-lms/sectionid"/>

With this pattern, we're able to achieve consistent results. It's complicated to be sure, but for cases appropriate for branch processing, is still more efficient than any other method we've found. In the use case I've excerpted, we reuse a couple dozen topics across 5 different learning platforms and 5 LMSs, so some topics are reused 25 times! The most common gotcha to look out for is not to inadvertently define a key in the root scope, preventing it being redefined in the scoped branch.

I hope this helps.

On Mon, Dec 21, 2020, 4:27 PM Stuart Norton via groups.io <snorton=juniper.net@groups.io> wrote:

Reece, thanks for sharing these links – sorry my Google-fu failed me, these are very helpful.

 

Stuart

 

 

Juniper Business Use Only

From: main@dita-users.groups.io <main@dita-users.groups.io> On Behalf Of r.roggen
Sent: Monday, December 21, 2020 7:54 AM
To: main@dita-users.groups.io
Subject: Re: [dita-users] conref and filtering

 

[External Email. Be cautious of content]

 

Branch filtering occurs in a different pre-processing stage than the args.filter-based processing. That may explain some of the discrepancies you'll see. When I'm tackling an issue with filters and conrefs or conkeyrefs myself, I usually go back and read these:


I've run into challenges like yours, and usually the solution (not ideal, but a solution) was to find a way to profile the source element rather than an element within the target. In your example, that might mean including <section> in the source topic and conref'ing in the <p> elements instead. There are many ways to address this, though, depending on your authoring environment and your reuse requirements.

Reece

Reece, thanks for sharing these links –