Re: conref and filtering

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">
        <ditavalref href="filters/lms/canvas.ditaval">
        <ditavalref href="filters/lms/brightspace.ditaval">
        <!-- 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"/>
        <!-- etc -->
    <topicref keyref="lms-bb.create-or-link-a-course">
        <topicref keyref="lms-bb.create-new-mt-course"/>
        <!-- etc -->

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 <> wrote:

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





Juniper Business Use Only

From: <> On Behalf Of r.roggen
Sent: Monday, December 21, 2020 7:54 AM
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, thanks for sharing these links –

Join to automatically receive all group messages.