Phase 1 Proposal: New "normal if used" Value for @processing-role

[Eliot Kimber <ekimber@contrext.com>]

In DITA 1.2 we introduced the @processing-role attribute on <topicref> with the values "normal" and "resource-only", where "normal" means "included in the normal flow of the publication" and "resource-only" means "used as a resource from other locations but not directly presented based on this topicref" (e.g., external resources like Web sites and images, "warehouse" topics used as conref targets, or topics used in multiple places in the publication via normal-role topicrefs.

I think we need a new value that means "use the referenced topic as a normal-role topic if and only if the topic is used from other normal-role topics, including from other normal-if-used topics that are themselves used by normal-role topics".

The processing result would be that topics referenced with the "normal if used" value are rendered only if used, otherwise they are filtered out (if the references occur in what would otherwise be a normal navigation structure, e.g. a literal glossary structure in a map) or not included in a generated navigation structure (e.g., produced by processing applied to <glossarylist>).

My use case is topics that are ultimately presented in the rendered publication as though they were referenced by normal-role topicrefs but where the inclusion of a given topic is dependent on its use from another topic, e.g., by xref or by <keyword> or similar keyref.

An obvious example of this is glossaries, where you have a large set of glossary entry topics but only want to include the final publication those glossary entries that are actually referenced.

From a map authoring standpoint you want to include all the *potential* glossary topics and then use markup (or your own business rules) to indicate where the glossary will be generated (e.g., an empty <glosslist> element or something).

At processing time a processor can then determine the set of glossary entries actually used from other topics (including glossary entries that refer to other glossary entries) and then dynamically generate the effective map structure you would have authored directly.

In this case the glossary entry topics are not appropriately "resource-only" topics because some or all of them will be included as normal-role topics. You wouldn't want, for example, an authoring tool to tell you that your link to a glossary entry topic is not good because the target is resource-only (oXygenXML will do this, for example).

I have implemented this kind of processing in my DITA Community glossary preprocessing extensions (presented and demonstrated at DITA North America) but it is hard coded specifically to references to glossary entries and also has to do tricks like replacing resource-only topicrefs with normal-role topicrefs with the same keys, which is a bit iffy as a general solution.

This proposal would provide a general indication of the author's intent and make it possible to have general map processing that is independent of the semantics of the elements involved.

Another example of this is from a sort of "database publishing" context where you have lots of (possibly generated) topics only some of which will ultimately be used by directly-authored topics. You don't know in advance which of these topics will be used (and the use could change at any time) so manually authoring the maps that use the subset of topics you actually want would be tedious and unnecessary (because the publication-time maps could always be generated by a purpose-built transform that understands the business rules for determining "is used" for a give topic). I have this use case at a current client. I'm currently solving it by preprocessing a "master" map to make "filtered" maps but that processing is expensive and results in multiple map documents that have to be maintained and kept up to date or regenerated very time the master map needs to be published.

So far I've only considered the need for a new value of @processing-role, but since one primary use case is generation of things like glossaries, there may also need to be additional attributes or metadata to use with generation-signalling elements like <booklist> and its specializations. But that might be best handled simply as a matter of processing style so I'm not sure we need anything.

My initial idea for the new value keyword is "normal-if-used".

Cheers,

Eliot

ï

--
Eliot Kimber
http://contrext.com