Re: [dita] Proposal 13063: Cross-references to conditional content

[Eliot Kimber <ekimber@reallysi.com>]

I would say it is user error. The Toolkit has an "only topics in map"
option, that prevents it from including topics that are referenced from
topics but not from the map tree, which is the case here.

Also, when you say 'The pricelist.xml file is conditionalized as audience =
"internal"' do you mean that the <topic> element has audience="internal" or
that the topicref to the topic has audience="internal"?

If the former, then the topic will always be filtered out, so I don't think
you mean that case. If the latter, then the "only topics in map" setting
should prevent that topic from being rendered. But that's a function of the
conditionality of the *topicref*, not the topic--the topic has no inherent
conditionality. 

Because DITA through 1.2 doesn't have a well-defined notion of referencing
topics in a specific use context (that is, in the context of a specific
topicref), there is no well-defined sense in which a direct xref to a topic
can know what applicability might have been imposed on that topic in its
different use contexts. For example, I could have this:

<topicref audience="internal"
  href="topics/pricelist.xml"/>
<topicref audience="external"
  href="topics/pricelist.xml"/>
<topicref  
  href="topics/pricelist.xml"/>

What is the topic's applicability? Can't tell. For the xref in question,
which of these three uses of the price list topic is intended? Can't tell.

If the xref was via key, then at least you could unambiguously determine
that the key definition is or isn't applicable, e.g.:

<topicref keys="pricelist-internal"
audience="internal"
  href="topics/pricelist.xml"
/>
<topicref keys="pricelist-external"
  audience="external"
  href="topics/pricelist.xml"
/>
<topicref keys="pricelist"
  href="topics/pricelist.xml"
/>

But in fact, a better solution would be to have different bindings for
different conditions to ensure that an unconditional reference to the price
list produces the correct result, e.g.:

<topicref keys="pricelist"
audience="internal"
  href="topics/pricelist.xml"
/>
<topicref keys="pricelist"
  href="topics/contact-sales-for-pricelist.xml"
/>

Which ensures that only a publication published for "internal" will see the
price list.

In the example as given, it is authorial error to include unconditionally a
link to a topic that may may not be applicable to both of the conditions to
which the topic applies. If the price list is only for internal use, the
reference to it (and any surrounding content) needs to be appropriately
conditional as well. Or you need to use the key-based solution as shown
above.

There is no way to know, in the general case, if an unresolvable link is
unresolvable because something is missing (left out or otherwise unavailable
for some reason) or because something was filtered out, or, if it was
filtered out, if the filtering was or was not appropriate.

I don't think there's any general way that a processor could know to
silently ignore an <xref> to a missing target. Even if the processor could
know that the target is missing because it was filtered out, it wouldn't
know what to do with any surrounding text, as in the example given.

[Note that this is a different case from that of an xref with content that
points to a key with no bound resource. In that case it can be argued that
the xref should not result in a link but its content should be rendered.]

The "only topics in map" Toolkit option solves the problem of unintended
inclusion of content resulting only from crossrefs or conrefs, so I think
the concern is manageable with the current tools.

As a matter of best practice I feel strongly that all topics used in a given
publication should be referenced from the map and the processing role of
resource-only makes that easy and reliable. If you do that, then you can
impose the "only topics in map" rule and use keys for all cross references
and conrefs and know that you have complete control at the map level over
what will and won't be included.

[Side note: I discovered an apparent bug in the Toolkit today whereby
specializations of @props are not applied when filtering maps. I logged it
as issue 3414270. That bug could affect ones ability to apply this principle
if you needed to filter on @props specializations, which almost everybody
almost always needs.]

Cheers,

Eliot


On 9/26/11 1:45 PM, "Su-Laine Yeo" <syeo@interelement.ca> wrote:

> Hi everyone,
> 
> I have an action from last week to email the group regarding proposal 13063,
> "Specify that if the target of a cross-reference should not appear in output,
> adding a cross-reference to it should not automatically make the target
> appear."
> 
> Here is an example in which the issue would arise. Say you have a file called
> "instructions.xml" which is conditionalized as 'audience="external internal"'.
> It includes the sentence, "Details are available in the <xref
> href="pricelist.xml">price list</xref>." The pricelist.xml file is
> conditionalized as audience = "internal". If you publish the instructions.xml
> file for audience = "external", it will include a link to the price list, and
> external users will be able to see the internal price list.
> 
> Is this a bug in the OT, or does the DITA spec currently allow this behaviour?
> 
> Here is a comment on the issue from Scriptorium
> (http://www.scriptorium.com/2010/11/to-ot-or-not-to-ot/):
> "Do you need a different set of criteria for conditional inclusion of topics
> than is provided by the default DITA OT?  Consider: if a topic is the target
> of a cross-reference, it will be included in the output even if that topic is
> excluded by the ditaval conditions.  Does that inclusion represent a security
> violation for your implementation?  Rewriting the conditional processing in
> the DITA OT can be done, but it is a serious challenge."
> 
> Regards,
> Su-Laine
> 
> Su-Laine Yeo
> Interelement Consulting: Communications and design for technology adoption
> www.interelement.ca
> syeo@interelement.ca
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dita-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: dita-help@lists.oasis-open.org
> 

-- 
Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 512.554.9368
www.reallysi.com
www.rsuitecms.com