DITA 1.3 cross-book linking in OT?

[Mark Giffin]

In watching the videos from DITA OT Day 2018 in Rotterdam, it appears that the OT does not yet implement DITA 1.3 cross-book linking. Is this true? I was planning to test it but maybe I will have to implement it first.

This video talks about it at about 26:00:

https://youtu.be/_bUsrS5wG7Y?t=1593

DITA 1.3 spec on "Cross-delivarable addressing and linking":

http://docs.oasis-open.org/dita/dita/v1.3/errata02/os/complete/part3-all-inclusive/archSpec/base/links-between-maps.html#links-between-maps

Thanks,

Mark Giffin

Mark Giffin Consulting, Inc.

http://markgiffin.com/

[Eliot Kimber]

The DITA OT does not implement cross-deliverable linking at this time. 

It's non-trivial to implement in a general way. It would require fairly deep rework of all the final-form transforms to produce a mapping from source elements that have associated keys to their deliverable-specific anchors. It also requires some mechanism for capturing the configuration details for the associations between a given root map and the deliverables generated from it, including the filtering conditions, any processor-specific parameters, and the time when the deliverable was generated. That is, you need some kind of "publication manager" functionality that at least provides the framework by which you can coordinate the publication details among a set of related publications. Basically, for all the publications in a set of publications that link to each other, you need to publish each one at least twice so that each deliverable for a given publication accurately reflects the anchors in the target deliverables from the other publications. 

In the context of a local environment where your implementation doesn't need to be so general the implementation can be easier because you can impose constraints or rely on conventions that simplify the problem. For example, if you don't use key scopes or branch filtering the problem becomes easier (because you assume a simple deterministic mapping from source keys and IDs or filenames to deliverable anchors, which you can't do in the face of key scopes or branch filtering).

Conceptually you have to maintain, for each root map from which a deliverable is generated, a set of mappings from source elements with associated keys and the deliverable-specific anchors they become so that you can then map references to those keys from other publications to the corresponding anchors (which also requires that you have a way to deciding which deliverable to link to for a given deliverable being linked from). 

These mappings could be maintained as sets of key definitions that replace the original source key bindings with bindings to the actual deliverables (using @scope = external and whatever @format value is appropriate) or they could be in a more traditional database of some sort. But you can completely define the cross-deliverable processing in terms of replacing sets of key definitions that point to the target publication's source with key definitions that point to anchors in a deliverable generated from the target publication.

I've been waiting for two things to happen before trying to implement this myself:

1. The OT 3.x code to stablize, in particular the preprocessing pipeline.

2. For a client to fund some or all of the work

1 is pretty close, I think. 2 I'm still waiting for, although I have had a couple of inquiries in the last month or so that may or may not pan out.

Cheers,

E.

--
You received this message because you are subscribed to the Google Groups "DITA-OT Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to dita-ot-user...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

Eliot Kimber

[Chris Papademetrious]

Reviving an old topic for context...

We're migrating from FrameMaker to DITA, our FrameMaker books had cross-book links (via post-processing of marker elements), and my writers want cross-book links in DITA.

I am looking to preserve DITA key references and definitions in the HTML5 output, to allow for a generalized link post-processor. Radu showed me how to preserve the @keyref attributes of <xref> elements in the output, so the reference half is solved.

Now I need to preserve the key definitions, so that "some_key" is captured inside the content-containing HTML element of whatever output HTML file it's in (based on chunking, etc.):

<topicref keys="some_key" href="mytopic.dita"/>

I've been looking through the XSLT code of various preprocessing modules, but I don't understand how to do something in a topic that looks at the map reference that instanced it.

Can someone point me in the right direction? I'm happy to share the solution if I get it working, of course.

Thanks!

 - Chris

To unsubscribe from this group and stop receiving emails from it, send an email to dita-o...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--

Eliot Kimber

[Chris Papademetrious]

Adding some HTML examples...

The part that's implemented is storing key references in the HTML using a data-keyref attribute:

For information about multithreading, see “<span class="xref topic/xref" data-keyref="cfug.enabling_multicore_processing">Enabling Multicore Processing</span>”

These span[@data-keyref] elements can be converted to an a[@href] via post-processing.

In the cfug book, this key resolves to the following topic:

    <topicref href="cfug/preparing_design/enabling_multicore_processing.dita" keys="enabling_multicore_processing">

So somehow I need to capture this key in the HTML of the cfug book, in the element that contains this reference:

<article role="article" aria-labelledby="ariaid-title1" data-keys="enabling_multicore_processing">
  <h1 class="title topic/title topictitle1" id="ariaid-title1">Enabling Multicore Processing</h1>
  <div class="body topic/body">
    <p class="p topic/p">Blah blah blah...

Ideally this stored key value would be the fully scoped value within its map. If that's not possible, I'll need to derive those scope values somehow - perhaps by directory name, or by analyzing the maps and output directories specified in a DITA-OT project file. Multiple scope levels would also require some careful thought. Plus, multiple keys could be defined to (point at) the same target element.

Ideally we'd maintain enough information in the HTML that the cross-book keyrefs would be fully resolvable for a set of HTML deliverables in their final production directory structure, without the need for side files or map analysis or other non-HTML dependencies.

 - Chris

[Chris Papademetrious]

I think storing the key definitions in the HTML is problematic for two reasons:

• If every topic has a key definition (per key best practices), it can add unused data to the HTML files.
  

• There can be multiple key definitions that point to the same topic.

Perhaps side files are a better approach. How can I extract a list of *all* key definitions from the transformation? Or can someone point me to where this information would be accessible in a processing stage?

Thanks!

 - Chris

[Chris Papademetrious]

If there are multiple @keys and/or @keyscope values, then the combinations multiply out. This:

<topicref href="mid.dita" keyscope="mid1 mid2" keys="midkey1 midkey2">
  <topicref href="low.dita" keyscope="low1 low2"  keys="lowkey1 lowkey2"/>
</topicref>

allows the following keyref values to access low.dita:

mid1.low1.lowkey1
mid2.low1.lowkey1
mid1.low2.lowkey1
mid2.low2.lowkey1
mid1.low1.lowkey2
mid2.low1.lowkey2
mid1.low2.lowkey2
mid2.low2.lowkey2

Of course, the side file could be constructed with spaces in the key values and let the postprocessor handle the combinations:

mid1 mid2.low1 low2.lowkey1 lowkey2: low.dita

with the scope levels period-separated, then the key names space-separated within each scope level.

 - Chris

[Radu Coravu]

Hi Chris,

If you set the transformation parameter "clean.temp" to "no" and publish, in the transformation temporary files folder there should be a file called something like "mapname_MERGED.xml" which should still have the keys defined on the chapters.

If you want this to work for our Oxygen CSS-based PDF publishing using HTML, I see that indeed this information is no longer available later on when the merged HTML document is constructed. Maybe my colleagues who work on this plugin could help with passing this information towards the generated HTML output.

Regards,

Radu

To unsubscribe from this group and stop receiving emails from it, send an email to dita-ot-user...@googlegroups.com.
To view this discussion on the web, visit https://groups.google.com/d/msgid/dita-ot-users/6a9d25c1-165c-4adb-af99-83b19e964e04%40googlegroups.com.

[Chris Papademetrious]

Hi Radu, all,

I confirmed that the final ditamap in the temp directory contains the key definitions with all chunking/copying/filtering applied. I think I can use this information to resolve cross-book keyrefs via a post-processor!

I can copy the merged map file to the HTML5 output directory with the following manual modifications to org.dita.html5/build_dita2html5.xml:

  <target name="dita2html5" depends="html5.init, build-init, preprocess, html5.topic, html5.map, html5.css, copy-map"/>

  <target name="copy-map">
    <basename property="dita.input.basename" file="${dita.input.filename}"/>
    <copy file="${dita.temp.dir}/${dita.input.basename}" todir="${dita.output.dir}"/>
  </target>

How can I package this extra processing step into a plugin? I tried going by the examples in the DITA-OT documentation, but I couldn't figure out how to add an extra step to an existing transformation type.

Getting closer!

 - Chris

To unsubscribe from this group and stop receiving emails from it, send an email to dita-o...@googlegroups.com.

[Radu Coravu]

Hi Chris,

There is a chance to add a custom ANT target just after the DITA pre-processing stage using the "depend.preprocess.post" extension point:

https://www.dita-ot.org/dev/extension-points/plugin-extension-points-pre-processing.html#ariaid-title1

Regards,

Radu

To unsubscribe from this group and stop receiving emails from it, send an email to dita-ot-user...@googlegroups.com.
To view this discussion on the web, visit https://groups.google.com/d/msgid/dita-ot-users/a33f0608-7e01-49f5-92a5-32f951b1ded4%40googlegroups.com.

[Chris Papademetrious]

Thanks Radu! This worked and I am able to proceed. I will work on the post-processing next.

 - Chris

To view this discussion on the web, visit https://groups.google.com/d/msgid/dita-ot-users/a33f0608-7e01-49f5-92a5-32f951b1ded4%40googlegroups.com.