Date   

Webinar: DITA 2.0: A Not Backwards Compatible Release, Part II on 05 October, 11AM EDT

Kristen James Eberlein
 

Join members of the OASIS DITA Technical Committee on Tuesday, 05 October 2021 to answer your questions about DITA 2.0. Because DITA 2.0 is NOT backwards compatible, we want to engage vendors and developers of DITA solutions early on.

In this 60-minute session, we'll answer your questions about DITA 2.0. We'll also provide links to the final grammar files for DITA 2.0, as well as drafts of the DITA 2.0 specifications.

This is a follow-up to the "DITA 2.0: A Not Backwards Compatible Release" Webinar held on Tuesday, 15 June 2021. You can view the slide deck and recording:

Please bring your questions to the Webinar. If you already know what questions you want to ask, please send them to me (kris@...) and we'll be sure to cover them!

Registration: https://us06web.zoom.us/webinar/register/WN_A7TKu4uHSIqj567ti1W6oA

Note: This Webinar series is targeted at developers of DITA tools, architects of DITA implementations, stylesheet developers, etc. The focus will not be on DITA 2.0 for authors.

Regards,
--
Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
OASIS Distinguished Contributor
Principal consultant, Eberlein Consulting LLC
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)



Re: Inconsistent clean-preprocess for Markdown to HTML5

Radu Coravu
 

Hello Chris, Nick,

If the .job.xml is written on disk at a very short interval (maybe less than a second) after it has been read, it is possible that the timestamp remains the same, at least we've had this problem on Linux in some automatic tests, in order to force the Java "file.getLastModified" method to be different we needed to make the test wait for a full second before writing to the file.

So if you have some kind of ANT task which changes the .job.xml maybe before calling it you can sleep for 1-2 seconds:

https://ant.apache.org/manual/Tasks/sleep.html

I do not know if this is the problem or not, but it's just something we have noticed with Java and the file system in general.

Regards,

Radu

Radu Coravu
Oxygen XML Editor
On 9/21/21 22:09, Chris Papademetrious wrote:

Hi Nick,

We get this "Reload stale job configuration reference" message intermittently too.

In our case, the message occurs because have a plugin that removes <draftintro> topics from the .jobs.xml file when args.draft is set to no. When the plugin modifies .jobs.xml, these two bits of code seem to detect the change in the .jobs.xml timestamp, then issue the message if a change to .jobs.xml is detected:


But this .jobs.xml change detection does not seem to be reliable. When the "Reload stale job configuration reference" message occurs, publishing completes normally. But when the message does not occur, then publishing continues to look for the deleted <draftintro> topic files:

[topic-fragment] Failed to process XML filter: Failed to transform file:/tmp/temp20210921150250573/_project_list_chrispy.dita: /tmp/temp20210921150250573/_project_list_chrispy.dita (No such file or directory)
[topicpull] Failed to transform document: Failed to transform document: I/O error reported by XML parser processing file:/tmp/temp20210921150250573/_project_list_chrispy.dita: /tmp/temp20210921150250573/_project_list_chrispy.dita (No such file or directory)

I don't know how rewrite rules work, but maybe they also somehow modify this .jobs.xml file and sometimes the file is not reloaded to reflect the changes.

I hope this helps!

 - Chris

  


Re: #DITA-OT #DITA-OT

Chris Papademetrious
 

Hi Dave,

Can you give a DITA example of a <resourceid> element that you have, and also an HTML example of what you'd like it to look like? (Or does it not matter, as long as it's there somehow?)

 - Chris


Re: Inconsistent clean-preprocess for Markdown to HTML5

Chris Papademetrious
 

Hi Nick,

We get this "Reload stale job configuration reference" message intermittently too.

In our case, the message occurs because have a plugin that removes <draftintro> topics from the .jobs.xml file when args.draft is set to no. When the plugin modifies .jobs.xml, these two bits of code seem to detect the change in the .jobs.xml timestamp, then issue the message if a change to .jobs.xml is detected:


But this .jobs.xml change detection does not seem to be reliable. When the "Reload stale job configuration reference" message occurs, publishing completes normally. But when the message does not occur, then publishing continues to look for the deleted <draftintro> topic files:

[topic-fragment] Failed to process XML filter: Failed to transform file:/tmp/temp20210921150250573/_project_list_chrispy.dita: /tmp/temp20210921150250573/_project_list_chrispy.dita (No such file or directory)
[topicpull] Failed to transform document: Failed to transform document: I/O error reported by XML parser processing file:/tmp/temp20210921150250573/_project_list_chrispy.dita: /tmp/temp20210921150250573/_project_list_chrispy.dita (No such file or directory)

I don't know how rewrite rules work, but maybe they also somehow modify this .jobs.xml file and sometimes the file is not reloaded to reflect the changes.

I hope this helps!

 - Chris


Inconsistent clean-preprocess for Markdown to HTML5

Nicholas Mucks
 

Hi!

We use rewrite rules for Markdown outputs in HTML so that the output folder structure looks as expected. For books with no dita topics (only markdown topics) we see inconsistent build failures where the failed builds do not perform the rewrites. We can run the same publish 10 times and it will fail 5 times, randomly.

Reviewing the verbose logs the only seemingly guilty root cause is that successful publishes always show “Reload stale job configuration reference” and “Overriding previous definition reference to job” for the clean-preprocess step.

How do we force the DITA-OT to alway reload the stale job reference for clean-preprocess? We tried setting both dita.preprocess.reloadstylsheet and dita.preprocess.reloadstylesheet.clean-map to “true” but that doesn’t resolve the inconsistency.

Thanks for sharing your thoughts. We are on DITA-OT 3.5.

Take care,
- Nick

Sent from mobile


Re: Keyref/conkey ref conversion strategy - keyref all the things? #conref

Chris Papademetrious
 

Hi Eliot,

Agreed, this feature is super convenient! And it removes another barrier to organizing keys and content nicely into submaps.

We did notice a a bug in 23.x versions where submaps (but not the top-level map containing them) get converted from LF-only to CR/LF when saved. This caused us issues with Git, which saw the newly added carriage returns as a change on every line. The bug will be fixed in Oxygen v24.0, due in mid-October from what I understand.

Also, you might be interested in this enhancement request to make the submap boundaries visible.

 - Chris


Re: Keyref/conkey ref conversion strategy - keyref all the things? #conref

ekimber@contrext.com
 

Another very useful setting I only just learned about is “Allow submaps to be edited”:

 

 

Means you can do everything from your root map, which makes it MUCH easier to be sure you have your root map context set correctly.

 

Cheers,

 

E.

 

--

Eliot Kimber

http://contrext.com

 

 

 

Hi everyone,

I created a perl script to automate @href-to-@keyref conversion for cross-references between topics:

https://github.com/chrispy-snps/DITA-convert-hrefs-to-keyrefs

Your map must already have @keys values defined for the topics; this script then automates the conversion of <xref> and <link> elements from @href to @keyref.

Note that Oxygen has a handy setting at

Tools > Preferences > DITA > Maps > Use the file name as the value of the "keys" attribute


to define @keys on new topics as you create them.

 - Chris


Re: Keyref/conkey ref conversion strategy - keyref all the things? #conref

Chris Papademetrious
 

Hi everyone,

I created a perl script to automate @href-to-@keyref conversion for cross-references between topics:

https://github.com/chrispy-snps/DITA-convert-hrefs-to-keyrefs

Your map must already have @keys values defined for the topics; this script then automates the conversion of <xref> and <link> elements from @href to @keyref.

Note that Oxygen has a handy setting at

Tools > Preferences > DITA > Maps > Use the file name as the value of the "keys" attribute

to define @keys on new topics as you create them.

 - Chris


Re: Local overrides of reused content

timathom@...
 

Thanks very much, Eliot and Jang! I will experiment with using key scopes for this use case.

All best,
Tim


--
Tim A. Thompson
Librarian for Applied Metadata Research
Yale University Library


Re: Local overrides of reused content

ekimber@contrext.com
 

If your content structure allows, you can do this by using a keyref from the re-used content and then have the key set to different values in different key scopes.

 

For example, in your reusable prolog block (in a warehouse topic) you would have something like:

 

<prolog>
    <author >Ann Author</author
    <source><ph keyref=”variable.source”/></source>
    <publisher>We Make Stuff</publisher>
    <critdates >…</critdates>
    <metadata >…</metadata>
</prolog>

 

And then your map or maps you can have different declarations for the key “variables.source”:

 

Map A:

 

<map>

  <topicgroup keyscope=”variable”>

     <topicmeta><navtitle>Keys for “variables”</navtitle></topicmeta>

     <keydef name=”source”>

       <topicmeta><linktext>Source A</linktext></topicmeta>

    </keydef>

  </topicgroup>

  <topicgroup keyscope=”reuse”>

     <topicmeta><navtitle>Warehouse Topics</navtitle></topicmeta>

     <keydef keys=”prologs” keyref=”reuse/prologs-warehouse.dita”/>

  </topicgroup>

     …

    <topicref href=”topics/topic-that-uses-proplog-01.dita”/>

</map>

 

Map B:

 

<map>

  <topicgroup keyscope=”variable”>

     <topicmeta><navtitle>Keys for “variables”</navtitle></topicmeta>

     <keydef name=”source”>

       <topicmeta><linktext>Source B</linktext></topicmeta>

    </keydef>

  </topicgroup>

  <topicgroup keyscope=”reuse”>

     <topicmeta><navtitle>Warehouse Topics</navtitle></topicmeta>

     <keydef keys=”prologs” keyref=”reuse/prologs-warehouse.dita”/>

  </topicgroup>

     …

    <topicref href=”topics/topic-that-uses-proplog-01.dita”/>

</map>

 

If the topic is used multiple times in a single map then you use distinct key scopes within the map and within each key scope define a different value for the source key.

 

Cheers,

 

E.

 

--

Eliot Kimber

http://contrext.com

 

 

 

Hello,

I am new to DITA and still learning the ropes (working in oXygen XML Editor v23). I have a question about content reuse: I have a set of reference topics, and I would like to reuse a common prolog block with standard metadata for all topics. However, each reference document needs to have a different source attribution. I know that I can do this:

<prolog>
    <author conkeyref="common/author_ref"/>
    <source>[Variable source info]</source>
    <publisher conkeyref="common/pub_ref"/>
    <critdates conkeyref="common/dates_ref"/>
    <metadata conkeyref="common/metadata_ref"/>
</prolog>

But rather than having to reference individual elements, I was wondering whether there was a way to reference the whole prolog and override the source element locally, like this:

<prolog conkeyref="common/prolog_ref">
  <source conaction="pushreplace" conkeyref="common/source_ref">[Variable source info]</source>
</prolog>


Of course, this only works from a single document because the common topic keeps getting overwritten by each push. Is there a way to do local overrides of reused content in DITA that I'm missing?

Thank in advance,
Tim


--
Tim A. Thompson
Librarian for Applied Metadata Research
Yale University Library


#DITA-OT #DITA-OT

davekoelmeyer@...
 

Hi folks,
 
I'm after a way to surface the resourceid element (specifically its appid attribute) of a DITA topic in DITA-OT's HTML5 output. I see from https://github.com/dita-ot/dita-ot/issues/2630 that this isn't supported in HTML5 output. But Radu's final comment indicates that I could possibly make a plug-in to do this.
 
Does anyone have experience doing this? I have no knowledge of DITA-OT plugin development; I can learn it but ideally someone could help with some information about whether it's feasible before I start.
It also looks like repurposing the Dublin Core plug-in for DITA-OT HTML5 might get me some of the way there, correct? (https://github.com/dita-ot/org.dita.html5.dublin-core)
---

For context: We use Oxygen XML Webhelp as one system for our docs. We have a new requirement to pipe the same content into various apps—basically to make in-app help. For various reasons, we cannot use WebHelp for the in-app help. So we're using a parallel publishing pipeline with a dedicated instance of DITA-OT. We need some method of assigning a UUID to each topic for the in-app help system; resourceid looks like the semantically correct element to use. The Oxygen folks helped me with a similar question about surfacing audience metadata (https://www.oxygenxml.com/forum/post63196.html); this was easy to do with Oxygen's XPath macro. So I'm basically after a similar result with DITA-OT.

Any help appreciated.

Cheers,
Dave


Re: Local overrides of reused content

 

Hello Tim,

You could do this type of thing by adding all possible content to the prolog and using profiling attributes to filter out the ones you do not want to see. Another option - if your variable source info is stored in a database - is to use my forthcoming Smart Product Data product, which allows you to an element in your DITA to items in a database. You can then define the item to be retrieved at the topic level, causing the right source information to be pulled into the <prolog> of every topic. I am still working on completing the product (need to create a GUI for <oXygen/> and complete the one for FrameMaker) but the basic method works and it looks like you could set the attribute values manually without running into trouble. It would be interesting to see a real-life solution based on my product. Check out the info on smartdata dot world and drop me a message if you are interested. 

Kind regards

Jang F.M. Graat

Smart Information Design
Amsterdam, Netherlands


Local overrides of reused content

timathom@...
 

Hello,

I am new to DITA and still learning the ropes (working in oXygen XML Editor v23). I have a question about content reuse: I have a set of reference topics, and I would like to reuse a common prolog block with standard metadata for all topics. However, each reference document needs to have a different source attribution. I know that I can do this:

<prolog>
    <author conkeyref="common/author_ref"/>
    <source>[Variable source info]</source>
    <publisher conkeyref="common/pub_ref"/>
    <critdates conkeyref="common/dates_ref"/>
    <metadata conkeyref="common/metadata_ref"/>
</prolog>

But rather than having to reference individual elements, I was wondering whether there was a way to reference the whole prolog and override the source element locally, like this:

<prolog conkeyref="common/prolog_ref">
  <source conaction="pushreplace" conkeyref="common/source_ref">[Variable source info]</source>
</prolog>


Of course, this only works from a single document because the common topic keeps getting overwritten by each push. Is there a way to do local overrides of reused content in DITA that I'm missing?

Thank in advance,
Tim


--
Tim A. Thompson
Librarian for Applied Metadata Research
Yale University Library


Re: [ANN] New release of the Oxygen Translator Helper add-on

Radu Coravu
 

Hi Tim,

The add-on just sends the text to translate to the web translators, there is no support in it for a glossary or terminology database.

Regards,

Radu

Radu Coravu
Oxygen XML Editor
On 9/10/21 15:15, SLAGER TIM via groups.io wrote:

This sounds great. Is there a way to connect the add-on to a glossary or terminology database?

 

From: main@dita-users.groups.io <main@dita-users.groups.io> On Behalf Of Radu Coravu via groups.io
Sent: Friday, September 10, 2021 4:32 AM
To: dita-users@groups.io
Subject: [dita-users] [ANN] New release of the Oxygen Translator Helper add-on

 

Hi everyone,

We updated the free Oxygen Translator Helper add-on to version 1.1.0 with additional support to use the DeepL translator for translating content.

To install it you can use the Oxygen main menu "Help->Install new add-ons", choose the default Oxygen add-on update site and you will find an add-on named "Translator Helper" in the list. To update the existing add-on you can use the Oxygen main menu Help->"Check for add-ons updates" action.

Just to recap, the add-on has two main features:

  1. You can translate content using "Google Translate" or "DeepL" to various languages:
    • Select the content to translate in the Author visual editing mode. You can also select the entire document contents but the translator might have limitations for the total amount they can translate.
    • Right click. Select "Translate->Google Translate" or "Translate->DeepL Translator" and choose the target language.
    • Copy the translated content from the opened web page.
    • Click Replace in the Oxygen Translate using Google Translate dialog that showed up. The original content should now be replaced with the translated content, the original element structure and attributes should remain unchanged.
    • In addition you can choose to show the original document content in the Translator Helper side view. This will allow you to correct the translation further by looking at the original text and the translated text side by side.
  1. You can see the original content side by side with the content that you are translating, so you can translate correctly and easy by right clicking in the Author visual editing mode and invoking the Show current content in side view action.

I hope you will find the updated add-on useful and as always any feedback for it is welcomed.

Regards,

Radu

Radu Coravu
Oxygen XML Editor
    

  


Re: [ANN] New release of the Oxygen Translator Helper add-on

SLAGER TIM
 

This sounds great. Is there a way to connect the add-on to a glossary or terminology database?

 

From: main@dita-users.groups.io <main@dita-users.groups.io> On Behalf Of Radu Coravu via groups.io
Sent: Friday, September 10, 2021 4:32 AM
To: dita-users@groups.io
Subject: [dita-users] [ANN] New release of the Oxygen Translator Helper add-on

 

Hi everyone,

We updated the free Oxygen Translator Helper add-on to version 1.1.0 with additional support to use the DeepL translator for translating content.

To install it you can use the Oxygen main menu "Help->Install new add-ons", choose the default Oxygen add-on update site and you will find an add-on named "Translator Helper" in the list. To update the existing add-on you can use the Oxygen main menu Help->"Check for add-ons updates" action.

Just to recap, the add-on has two main features:

  1. You can translate content using "Google Translate" or "DeepL" to various languages:
    • Select the content to translate in the Author visual editing mode. You can also select the entire document contents but the translator might have limitations for the total amount they can translate.
    • Right click. Select "Translate->Google Translate" or "Translate->DeepL Translator" and choose the target language.
    • Copy the translated content from the opened web page.
    • Click Replace in the Oxygen Translate using Google Translate dialog that showed up. The original content should now be replaced with the translated content, the original element structure and attributes should remain unchanged.
    • In addition you can choose to show the original document content in the Translator Helper side view. This will allow you to correct the translation further by looking at the original text and the translated text side by side.
  1. You can see the original content side by side with the content that you are translating, so you can translate correctly and easy by right clicking in the Author visual editing mode and invoking the Show current content in side view action.

I hope you will find the updated add-on useful and as always any feedback for it is welcomed.

Regards,

Radu

Radu Coravu
Oxygen XML Editor_._,_._,_


Open position in Dallas! #jobhunting

Josh Steves
 

My company, International Risk Management Institute, is hiring a Content Architect for our Ops team!

Apply HERE!


[ANN] New release of the Oxygen Translator Helper add-on

Radu Coravu
 

Hi everyone,

We updated the free Oxygen Translator Helper add-on to version 1.1.0 with additional support to use the DeepL translator for translating content.

To install it you can use the Oxygen main menu "Help->Install new add-ons", choose the default Oxygen add-on update site and you will find an add-on named "Translator Helper" in the list. To update the existing add-on you can use the Oxygen main menu Help->"Check for add-ons updates" action.

Just to recap, the add-on has two main features:

  1. You can translate content using "Google Translate" or "DeepL" to various languages:
    • Select the content to translate in the Author visual editing mode. You can also select the entire document contents but the translator might have limitations for the total amount they can translate.
    • Right click. Select "Translate->Google Translate" or "Translate->DeepL Translator" and choose the target language.
    • Copy the translated content from the opened web page.
    • Click Replace in the Oxygen Translate using Google Translate dialog that showed up. The original content should now be replaced with the translated content, the original element structure and attributes should remain unchanged.
    • In addition you can choose to show the original document content in the Translator Helper side view. This will allow you to correct the translation further by looking at the original text and the translated text side by side.
  2. You can see the original content side by side with the content that you are translating, so you can translate correctly and easy by right clicking in the Author visual editing mode and invoking the Show current content in side view action.
  3. Image

I hope you will find the updated add-on useful and as always any feedback for it is welcomed.

Regards,

Radu

Radu Coravu
Oxygen XML Editor


Re: Displaying links between DITA topics as a diagram

Radu Coravu
 

Hi Eliot,

Right, I had the same experience with a diagram generated for the Oxygen user's manual (about 1200) topics.

I'm not sure if the amount of nodes or the amount of links makes the library slow, probably a combination of these.

Regards,

Radu

Radu Coravu
Oxygen XML Editor
On 9/4/21 01:49, ekimber@... wrote:

I lied—my 8K node network did display, it just took the browser several minutes to open it!

 

Cheers,

 

E.

 

--

Eliot Kimber

 

 

 

From: <main@dita-users.groups.io> on behalf of "ekimber@..." <ekimber@...>
Reply-To: <main@dita-users.groups.io>
Date: Friday, September 3, 2021 at 5:41 PM
To: <main@dita-users.groups.io>
Subject: Re: [dita-users] Displaying links between DITA topics as a diagram

 

Radu,

 

Like Chris, we’re struggling with large numbers of links and moving to cross-deliverable links.

 

I tried running it on one of our root maps, which ultimately involves about 8000 topics (even though the input map only refers to about 115 topics!).

 

Unfortunately, it said that the improved layout couldn’t position the network with the improved layout engine and it’s a holiday weekend so I’ll come back to it

 

But like Chris I was about to try to make something like this myself, so you’ve saved me much time (yet again).

 

Cheers,

 

E.

 

--

Eliot Kimber

 

 

 

From: <main@dita-users.groups.io> on behalf of Radu Coravu <radu_coravu@...>
Reply-To: <main@dita-users.groups.io>
Date: Thursday, September 2, 2021 at 11:58 PM
To: <main@dita-users.groups.io>
Subject: Re: [dita-users] Displaying links between DITA topics as a diagram

 

Hi Chris,

With pleasure, indeed creating the small JSON data part of the file is quite easy, VisJs has lots of settings which can be switched as well but I have not played much with them.

Regards,

Radu

Radu Coravu
Oxygen XML Editor

On 9/2/21 22:23, Chris Papademetrious wrote:

Hi Radu,

This visualization is pretty cool! I appreciate the example graph so we could easily see what is produced without running all the steps.

Our books have cross-deliverable links using peer maps (<mapref scope="peer">) with keyscopes. I have considered writing a script to extract a similar graph for book-to-book references, so we can see how our books - and thus our products - tend to reference each other. Your example gives me a great example of how the visualization part could work. I was originally going to create a static drawing using GraphViz, but I like this interactive VisJS approach better.

Thank you for sharing this!

 - Chris

 

  


Re: Displaying links between DITA topics as a diagram

ekimber@contrext.com
 

Our content currently does not use keys for cross references, so if you don’t specify only-topic-in-map, OT chases down all the topic-to-topic links, wherever they might lead.

 

For keys in topics that are not referenced from the map the correct thing to do is refuse to resolve them, which is what newer versions of Open Toolkit does.

 

Cheers,

 

E.

 

--

Eliot Kimber

http://contrext.com

 

 

 

Hi Eliot,

I'm curious - how are you getting more topics in your output than exist in your map?

Let's say I have bookA that references bookB as a peer map:

<?xml version="1.0" encoding="UTF-8"?>

<?xml-model href="urn:oasis:names:tc:dita:rng:map.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>

<map>

    <title>Book A</title>

    <mapref href="bookB.ditamap" keyscope="bookB" processing-role="resource-only" scope="peer"/>

    <topicref href="bookA/topic1.dita" keys="bookA_topic1"/>

    <topicref href="bookA/topic2.dita" keys="bookA_topic2"/>

</map>


Now let's say I have a bookA topic that has a cross-book link to "topic3" in bookB. If that cross-book link uses  @keyref:

<p>For details, see <xref keyref="bookB.topic3">Topic 3 in Book B</xref>.</p>


then the published output has only the bookA topics:

$ ls -1 out/*/*.html

out/bookA/topic1.html

out/bookA/topic2.html


But if I try to create the cross-book link as an @href instead:

<p>For details, see <xref href="../bookB/topic3.dita">Topic 3 in Book B</xref>.</p>


then the target topic is included in the published output, which is not correct behavior for a peer map:

$ ls -1 out/*/*.html

out/bookA/topic1.html

out/bookA/topic2.html

out/bookB/topic3.html


I wonder if you have cross-book links that use @href instead of @keyref, thus causing transformation to promiscuously include the target topics in the output?

(There is another issue with "cross-book" @href links, in that Oxygen's validator traces into them during validation but in the original book's key scope, which tends to cause spurious "unresolved key" validation errors in target topic content.)

 - Chris


Re: Displaying links between DITA topics as a diagram

john.kirkilis@...
 

In addition, here are a couple of other JS node mapping libraries I've looked into:

41 - 60 of 46441