Using conkeyref with DITA glass transform

[jayaram]

Hi,

I am trying to figure how I can do keydefs and conkeyrefs when I have several markdown files and several DITA files. Is there any example that I can look at to see how it could be possible?

Specifically, my situation is as follows:

1. Markdown files that need to pull in some markdown content (mostly references to images and some text) via conkeyref
2. DITA files that will conkeyref the above MD files
3. DITA maps that contain topicrefs to the DITA files and MD files above and will be used to build a PDF as well as SCORM output.

I greatly appreciate any help.

Thanks,
Jayaram

[Radu]

Hi Jayaram,

I assume that you have downloaded and tested our DITA Glass GitHub project:

https://github.com/oxygenxml/dita-glass

Please see some possible answers below:

1. Markdown files that need to pull in some markdown content (mostly references to images and some text) via conkeyref

I'm not sure there are markdown constructs to do this. But as you saw in the example in which the markdown file is referenced in the DITA Map:

Code: Select all

<topicref href="convert:/processor=xslt;ss=urn:processors:h2d.xsl/processor=xhtml/processor=js;js=urn:processors:md:Markdown.Converter.js;fn=convertExternal!/urn:files:sample.md" format="dita"/>

you are in control of the pipeline, you control the Javascript converter which gets applied on the original Markdown to convert it to HTML and the XSLT converter which converts the XHTML to DITA. So you can perform your own processing there.

2. DITA files that will conkeyref the above MD files

Again, by modifying the XSLTs and the Javascript conversion stage you control the content of the DITA topic obtained from the MD file. So you can for example set IDs on various elements in the converted DITA topic in order to reuse them from other topics.

3. DITA maps that contain topicrefs to the DITA files and MD files above and will be used to build a PDF as well as SCORM output.

The DITA Glass project has a DITA map which references various formats and can be published to WebHelp or PDF using some predefined transformation scenarios. Not sure about SCORM output, I remember there was a DITA OT plugin for it but I have not used it.

Regards,
Radu

[jayaram]

Hi Radu,

Thanks for your reply. I will give some example to hopefully work through this. My top level map has:

Code: Select all

<map>

 <title>DITA Glass</title>

  <topicref href="resources/images-md/imagekeys.ditamap" format="ditamap"></topicref>

  <topicref href="contentkeys.ditamap" format="ditamap"></topicref>

  <topicref href="App-formulas.dita" format="dita"/>

 

</map>

App-formulas.dita has:

Code: Select all

<concept id="concept-1-zKuLfRBb" xml:lang="en"><title>App formulas</title>

    <conbody>

        <p conkeyref="cont-app-formula"/>

    </conbody>   

</concept>

The warning in Author is:

[Document]:Conref was not expanded:
The source element "p" with class value "- topic/p " is not a generalization of target element "topic" with class value "- topic/topic "

My lower level contentkeys.ditamap has:

Code: Select all

<map>

 <title>AppSheet Content</title>

 <keydef keys="cont-app-formula" href="convert:/processor=xslt;ss=urn:processors:h2d.xsl/processor=xhtml/processor=js;js=urn:processors:md:Markdown.Converter.js;fn=convertExternal!/urn:files:App-formulas.md" format="dita"/> 

</map>

and imagekeys.ditamap has:

Code: Select all

<map>

 <title>AppSheet Images</title>

 <keydef keys="img-app-formula-btn" href="img-app-formula-btn.dita"/>

</map>

When I run the PDF transform, I get the message:

[DOTX015E]: The attribute conref="urn_files_App-formulas.md.dita" uses invalid syntax. The value should contain '#' followed by a topic or map ID, optionally followed by '/elemID' for a sub-topic element.

What I want to know is how to fix this?

Thanks,
Jayaram

[Radu]

Hi Jayaram,

The syntax of a conkeyref needs to be something like:

Code: Select all

<p conkeyref="keyName/targetElementID"/>

You already have the key name set on the keydef but you also need to point to the ID of a paragraph which will be reused.
So you should try to change the XSLT stylesheet used to generate the topic from the markdown in order to generate IDs on all elements that you want to reuse.

The same thing about the conref, the syntax of the conref attribute should be something like:

Code: Select all

conref="convert:/processor=xslt;ss=urn:processors:h2d.xsl/processor=xhtml/processor=js;js=urn:processors:md:Markdown.Converter.js;fn=convertExternal!/urn:files:App-formulas.md#topicID/elementID" 

where the topic ID is the ID of the topic root element and the elementID again needs to be present after the conversion.

Regards,
Radu

[jayaram]

Hi Radu,

Thanks for clarifying that - I don't know if I am making it more complicated than it needs to be.

Anyway, I was wondering about other possibilities:

1. What if I want to insert the entire contents (and not a specific element inside it) of the .md file into App-forumulas.dita file ? It would be easiest if I could say <topic conkeyref="cont-app-formula"/> inside App-forumulas.dita but I can't.

2. Maybe I can save the DITA file generated from the .md file, and do a two stage conversion with two ditamaps. After running the conversion using the first ditamap, I could run a script that updates the intermediate DITA file with elementIDs and modifies the conkeyrefs appropriately.

I am trying to find the best alternative.

Regards,
Jayaram

[Radu]

Hi Jayaram,

1. What if I want to insert the entire contents (and not a specific element inside it) of the .md file into App-forumulas.dita file ? It would be easiest if I could say <topic conkeyref="cont-app-formula"/> inside App-forumulas.dita but I can't.

Yes, this should work. What problem does it report if you try it?

2. Maybe I can save the DITA file generated from the .md file, and do a two stage conversion with two ditamaps. After running the conversion using the first ditamap, I could run a script that updates the intermediate DITA file with elementIDs and modifies the conkeyrefs appropriately.

Yes, you could also have some custom processing which from time to time converts markdown files to dita files and keeps them perfectly synchronized.
Also an alternative to DITA Glass is this DITA Open Toolkit plugin which again can be used to convert markdown files referenced in the DITA Map to DITA Topics:

https://github.com/jelovirt/dita-ot-markdown

Regards,
Radu

[jayaram]

Hi Radu,

I was able to get the entire topic to be transcluded using the topic with the <topic conkeyref="cont-app-formula"/> syntax. The error I saw before was because I did not do it with the project settings of dita-glass.

Also, thanks for the pointer about data-ot-markdown. I am able to install the plugin to the Oxygen tree and run it via command line but when I run a transform in Oxygen, I am getting the following error:

[DOTJ013E] Failed to parse the referenced file 'file:/Users/user/Documents/DITA/dita-ot-markdown/src/test/resources/codeblock.md'.: com.elovirta.dita.markdown.MarkdownReader

I even ran the DITA OT Integrator transform but still seeing this. What am I doing wrong?

Thanks,
Jayaram

[Radu]

Hi Jayaram,

I'm glad the first part works for you.
About trying the DITA OT Markdown plugin, you should edit the transformation scenario and in the "Advanced" tab there is a Libraries button. In the Libraries list you should add additional references to all libraries needed by the MarkDown plugin, which are in the folder:

OXYGEN_INSTALL_DIR\frameworks\dita\DITA-OT2.x\plugins\com.elovirta.dita.markdown

Regards,
Radu