Displaying links between DITA topics as a diagram


Radu Coravu
 

Hi everyone,

About a week or two ago I experimented with taking a DITA Map and using the VisJS Javascript library to create a diagram containing nodes for each topic along with arrows showing which topics refer to each other.

I wrote a blog post about this if anyone else is curious to try this out:

https://blog.oxygenxml.com/topics/creating_graphs_from_dita_maps.html

and here's the graph that is obtained for the Oxygen XML Blog DITA Map:

https://blog.oxygenxml.com/resources/sampleGraphBlog.html

You can interact with the diagram by dragging topics or using the mouse wheel to zoom in or out.

Regards,

Radu

Radu Coravu
Oxygen XML Editor


Chris Papademetrious
 

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


Radu Coravu
 

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

  


ekimber@contrext.com
 

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

http://contrext.com

 

 

 

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

 


ekimber@contrext.com
 

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

 

Cheers,

 

E.

 

--

Eliot Kimber

http://contrext.com

 

 

 

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

http://contrext.com

 

 

 

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

 


Chris Papademetrious
 

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


john.kirkilis@...
 

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


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


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