Discovering the right extension point

[xephon]

Hi,

I need to generate a custom filtered XML file containing keys and relative URLs to the physical XHTML output files. This is my map (pseudocode):

Code: Select all

<map>

  <topicref keyref="MyTopic1" audience="Admin"/>    

  <topicref keyref="MyTopic2"/>

  <topicref keyref="MyTopic3"/>

  <topicref keyref="MyTopic4" audience="Admin"/>

  <topicref keyref="MyTopic5" audience="Admin"/>

</map>

This is what I need:

Code: Select all

<links>

  <link key="MyTopic2" path="path/to/my/topic2.html"/>

  <link key="MyTopic3" path="path/to/my/topic3.html"/>

</links>

So, what I (think I) have to do is this:

• Filter the map
• Store the keys temporarily
• Resolve the keys (because I need the relative path)

According to the DITA-OT processing-order, this should work.

I'm going to write a new DITA-OT plugin and add it as a dependency to the Webhelp pipeline. It would be nice, if I could avoid writing Java and stick to XSLT. Now, here is my question :

How would you proceed?

How can I examine/debug the processing pipeline to find out the correct extension point to pick the information I need to generate the file? I have only low experience with debugging DITA-OT plugins, because usually it is enough to override dita.xsl.xhtml.

I'd appreciate any hints, links or tutorials.

Thanks a lot and best regards
Stefan

[Radu]

Hi Stefan,

I'm not sure.

There seem to be some pre-processing Java extensions listed here:

http://www.dita-ot.org/2.0/dev_ref/plug ... ocess.html

How about if you apply an XSLT stylesheet on the map after the entire WebHelp processing is done?
You could for example create your custom ANT build file which calls the DITA OT main build file:

http://www.oxygenxml.com/doc/ug-oxygen/ ... -file.html

and after the main processing is done it could call an XSLT task which gets applied on the map and generates that file.

If what you are after is a context-sensitive webhelp system, the WebHelp bundled with Oxygen 17 already has this functionality:

http://www.oxygenxml.com/doc/ug-oxygen/ ... ystem.html

It creates a mapping file based either on the topic ID or on the <resourceid> element defined in each DITA topic.

Regards,
Radu

[xephon]

Hi Radu,

wow , you surprised me another time. The context-sensitive webhelp system is exactly what I need. Unfortunately I have no budget for an Oxygen upgrade in this quarter and I need that system now. But that is definitely a really cool new Oxygen feature. Thanks a lot

However, according to your documentation, I would not be able to use keys for the webhelp system. Currently we don't care much for topic IDs or resource IDs, because they seemed to be insignificant.

Your docs says:

Invoke one of the WebHelp system files index.html or index_frames.html and pass them the contextId parameter with a specific value.

Is that already working with Oxygen 16?

How about if you apply an XSLT stylesheet on the map after the entire WebHelp processing is done?

Hmm... the point is, that I want to process the filtered map, so I don't want to include mappings to content that does not exist in my publication. So my idea was to pick that map after it has been filtered but before the links are resolved. It would be possible to process the map, as you mentioned, after the WebHelp processing. But my intention was to avoid rebuilding the filter mechanism. And I think this would be what I have to do, if I follow your recommendation.

Further on, as I understand, I cannot call the WebHelp processing by Ant, because I need a special license for that. So I'd have to use an extension point, but that's no issue.


Greetings and best regards
Stefan

[Radu]

Hi Stefan,

Please see some answers below:

However, according to your documentation, I would not be able to use keys for the webhelp system. Currently we don't care much for topic IDs or resource IDs, because they seemed to be insignificant.

The DITA <resourceid> element was intended especially for such cases.
I would consider it more suitable for use when doing context sensitive WebHelp.

Your docs says:
Invoke one of the WebHelp system files index.html or index_frames.html and pass them the contextId parameter with a specific value.
Is that already working with Oxygen 16?

Unfortunately not.

How about if you apply an XSLT stylesheet on the map after the entire WebHelp processing is done?
Hmm... the point is, that I want to process the filtered map, so I don't want to include mappings to content that does not exist in my publication. So my idea was to pick that map after it has been filtered but before the links are resolved. It would be possible to process the map, as you mentioned, after the WebHelp processing. But my intention was to avoid rebuilding the filter mechanism. And I think this would be what I have to do, if I follow your recommendation.

Possibly if you avoid removing the temporary files folder you will find in it the DITA Map with some parts already filtered out.

Further on, as I understand, I cannot call the WebHelp processing by Ant, because I need a special license for that. So I'd have to use an extension point, but that's no issue.

Transformations which apply DITA OT processing are ANT based. So you can edit the transformation scenario and in the Advanced tab set a path to the custom build file which could invoke the DITA OT main build file and do other stuff before or after it.

http://www.oxygenxml.com/doc/ug-oxygen/ ... -file.html

Regards,
Radu

[xephon]

Hi Radu,

I followed your recommendations and came up with this target:

Code: Select all

<target name="generateContextHelpMap">

    <!-- Call the DITA init target. -->

    <antcall target="init"/>

    <xslt

      extension=".xml"

      basedir="${dita.temp.dir}"

      includes="myFirst.ditamap,

                mySecond.ditamap"

      style="${dita.dir}/plugins/myPlugin/xsl/context.xsl"

      destdir="${dita.temp.dir}"/>

    <copy 

      file="${dita.dir}/plugins/myPlugin/template/context-help-map.xml"

      todir="${dita.temp.dir}"/>

    <xslt

      basedir="${dita.temp.dir}"

      includes="context-help-map.xml"

      style="${dita.dir}/plugins/myPlugin/xsl/merge.xsl"

      destdir="${dita.temp.dir}">

      <param name="dita.temp.dir" expression="${dita.temp.dir}"/>

      <param name="output.dir" expression="${output.dir}"/>

    </xslt>

    <copy 

      file="${dita.temp.dir}\context-help-map.html"

      tofile="${output.dir}\context-help-map.xml"/>

    <copy 

      file="${dita.dir}\plugins\myPlugin\template\context-help-map.xsd"

      todir="${output.dir}"/>

    <delete dir="${dita.temp.dir}"/>

  </target>

It works great. I use the XML structure of your Context-Sensitive WebHelp System to be well prepared for Oxygen 17.


Thank you and best regards
Stefan

[Radu]

Hi Stefan,

I'm glad this works for you. Thanks for updating this thread with your current solution.

Regards,
Radu