Re: Allow variables to be referenced from @scope="peer" maps


ekimber@contrext.com
 

This is an example of where a local, targeted solution is relatively easy (just a bit of preprocessing or relying on knowledge of cases that won't occur in your content) but the general solution would be hard (because it has to handle all cases, perform well, be extensible, report exception conditions clearly, etc.).

It's not hard to implement simple processes that operate on maps and do specific things, either using the output of the OT preprocessing stage or just operating on the maps directly if you know you don't need to worry about stuff like filtering, metadata propagation, etc.

The DITA Community utilities area on github has general XSLT scripts for operating on maps, including resolving key references and resolving topicrefs to topics. With that code as a base it should be as easy as it can be to extract topic titles or book titles. https://github.com/dita-community/dita-utilities/tree/master/src/xslt

Then, as you say, it's a matter of optimizing performance: do you do the processing every time or cache results? If you cache results, how do you keep the cache up to date?

Cheers,

E.

--
Eliot Kimber
http://contrext.com


´╗┐On 1/25/21, 8:06 AM, "Chris Papademetrious" <main@dita-users.groups.io on behalf of chrispitude@gmail.com> wrote:

Hi Eliot, David,

Thanks to both of you for sharing your thoughts!

Some background information... We use cross-book links in our content. On the authoring side, we have a compiled Perl script (accessible as an external tool in Oxygen) that populates cross-book link target text in the DITA source files. On the production side, we use a variant of the following plugin to late-resolve links in the final HTML output:

https://github.com/chrispy-snps/DITA-fix-xbook-html-links

Thus, many of our books already reference other books as peer maps.

A writer asked me how to get the title of a referenced book so she could get the title of a peer-referenced book, something like this:

<p>See <ph keyref="bookB.BookTitle"/> for more information.</p>

I thought it would be neat to define a BookTitle variable in every book, even using its value as the <bookmap> title so the title is single-sourced everywhere from the variable. Clever me! But this is when I found out that variables in peer maps are not accessible.

Could I solve this by defining every book title in a shared "booktitles" map, then referencing that map from every book? Well sure I guess, but yuck. Every book has a title, I just want to get to it.

Right now DITA offers


* @scope="peer" maprefs (ignores map+topic content)
* @scope="local" maprefs (processes map+topic content)


Functionally, I want something between these. I want to process a peer book's map structure but not its topic content, with the exception of preserving topic <title> elements to enable processing to populate cross-book link target text.

This would elegantly solve some challenges we have with cross-book links to topics with conditional-content titles, as then the DITA-OT profiling behaviors simply play out in the peer maps and resolve the content for us. Currently our Perl script flags these for human intervention. It would also avoid issues with stale target text because the target topic title changed but the referencing-topic writer didn't know to rerun the Perl script.

Would this increase processing time? Sure, but I'd gladly exchange that for the flow simplification. And if I can figure out how to ignore <body> elements during peer-map topic read-in, the vast bulk of the peer map content would never even make it into memory; we'd basically just have skeleton peer maps available to resolve references, and the processing overhead should be minimal.

I'm going to try hacking my way through this to see how far I get. I will definitely follow up here with my progress, and I will likely follow up with questions. :)

- Chris

Join main@dita-users.groups.io to automatically receive all group messages.