Oxygen XML Forum

Posted: **Mon Nov 18, 2019 2:52 am**

Hi all,

Many of our topic files have subtopics nested in the same physical topic file. For example,

<topic id="CIHJIEEE">
 <title>About This Manual</title>
 <topic id="X2Tw8aq9SqTGl9W3GCTN5-w">
  <title>Audience</title>
  </topic>
  <topic id="BABFAGGE">
   <title>Related Publications</title>
  </topic>
  <topic id="XZ4xwGZck2ksmiNJ69aZRiQ">
    <title>Conventions</title>
  </topic>
</topic>

Each of these subtopics must be explicitly referenced in the map file, for example:

Code: Select all

      <topicref href="tclug/preface/about_this_manual.dita" keys="about_this_manual">
        <topicref href="tclug/preface/about_this_manual.dita#X2Tw8aq9SqTGl9W3GCTN5-w" keys="audience"/>
        <topicref href="tclug/preface/about_this_manual.dita#BABFAGGE" keys="related_publications"/>
        <topicref href="tclug/preface/about_this_manual.dita#XZ4xwGZck2ksmiNJ69aZRiQ" keys="conventions"/>
      </topicref>

We require this flow because our writers want the content chunking in the editor to directly represent what the end-users will see in our online help.

The question is, how do we keep the map file updated to reflect the subtopic structures created by the writers? Asking the writers to keep this up-to-date via the DITA Maps Manager is awkward and error-prone.

I've written a perl script that accepts one or more topic filenames, then adjusts any referencing map files to reflect the subtopic structures (if needed) It preserves existing @keys values when subtopics are moved or reordered by editing. It returns the list of updated map filenames to stdout.

However, the script causes the XML to be reformatted, which drastically increases the Git footprint. I'm unable to replicate Oxygen's "Format and Indent Files" feature well enough to avoid false Git differences.

So the magic question is,

When a user saves a topic file, how can I (1) run an external program with the topic file as the argument, (2) wait for the external program to complete, then (3) call the Format and Indent Files feature on all map files returned by the external program?

I can return the list of referencing map files from the external program. And of course I'm happy to share everything with the forum once I get it working.

Thanks!

- Chris

Posted: **Mon Nov 18, 2019 10:43 am**

Hi Chris,

So:

(1) run an external program with the topic file as the argument,

A sample Oxygen java-based workspace access plugin project can be found here:

https://github.com/oxygenxml/sample-plu ... ace-access

Once an XML document is opened, it's controlled via the "WSEditor" API which allows you to add a listener:

ro.sync.exml.workspace.api.editor.WSEditor.addEditorListener(WSEditorListener)

and the listener has a callback method:

ro.sync.exml.workspace.api.listeners.WSEditorListener.editorSaved(int)

When the editor is saved you can start a new process:

https://stackoverflow.com/questions/377 ... ss-in-java

(2) wait for the external program to complete,

You can block the Java code until the processs is over:

https://docs.oracle.com/javase/8/docs/a ... #waitFor--

Ideally in order not to block the entire application when saving you should start a new Java thread which starts the process, blocks until it finishes and then...

(3) call the Format and Indent Files feature on all map files returned by the external program?

You have this API method:

ro.sync.exml.workspace.api.PluginWorkspaceProvider.getPluginWorkspace().getXMLUtilAccess().prettyPrint(reader, systemID)

https://www.oxygenxml.com/InstData/Edit ... vider.html

You will need to provide it a reader over the file and an URL pointing to the file.

Regards,
Radu

Posted: **Mon Nov 18, 2019 7:28 pm**

Hi Radu,

This is great information and Java is surely the right way to do this. Unfortunately I don't know any Java beyond "hello world" and so such a solution is not workable in my timeframe (which is tomorrow-ish!).

For now, I have written a perl script that takes one or more topic filenames as input, then updates any maps pointing to those topics with subtopic structures inside those topics. Although I developed the script in linux, I compiled it to a Windows .exe file using Strawberry Perl, then configured it as an external tool in Oxygen:

: tool.png (14.6 KiB) Viewed 1277 times

Here are the instructions I gave to the writers:

When you are editing a topic and you've made changes to the subtopic or module structure within that topic file, run this tool to update all maps that reference this topic. If you are reordering subtopics or modules in the topic file, it will preserve their key values in the maps. If you create new subtopics or modules (or move them to another topic file - current limitation), it will create new key values based on the subtopic/module title.

The menu item runs a Windows-compiled perl script which is slow and inefficient, but it's what I could come up with in our needed timeframe.

When the script completes, click in the DITA Maps Manager and Oxygen will notice the modified bookmap file and reload it. Then click back in the topic editing window and Oxygen will open that topic's map entry, which should now contain the updated subtopic/module entries. You can verify the changes by going to the Git Staging view and right-clicking your bookmap file and comparing your modified version to the repo version.

In our books, we have a <module> element that is specialized from <topic> that should always have @toc="no", so there are some references to 'module' elements that wouldn't be needed in generic DITA.

This script is simplistic and hastily written, but it works for us for now.

update_map_v0.1.zip: (2.31 KiB) Downloaded 199 times

Posted: **Tue Nov 19, 2019 8:47 am**

Hi Chris,

Thanks for posting the solution, maybe others will find it useful.

Regards,
Radu

Posted: **Wed Nov 20, 2019 4:52 pm**

Thanks Radu! It has been working well in practice. When a user has made changes to a topic's subtopic structure, they (1) run the tool from the menu item, (2) click into the DITA Maps Manager, which reloads the changed map file, then (3) click back into the editing window, which expands the map to that topic's location. The whole process takes about five seconds.

Posted: **Sat Nov 30, 2019 4:28 am**

I've updated the script to behave as follows:

When a topic is open, all map references** to that topic are updated.
When a map is open but a topic is not, all map references** to topics in the open map are updated.
When no map or topic is open and the current map context is set to <Current map>, all map references to all topics are updated.

**This behavior ensures that all maps are updated if a topic is shared by multiple maps.

The command line in the External Tools configuration should now be as follows:

Code: Select all

"${pd}/prj/tools/update_map/update_map.exe" "${cf}" "${rootMapFile}"

update_map_v0.2.zip: (2.68 KiB) Downloaded 185 times

Oxygen XML Forum

updating bookmap with nest subtopic structure in a topic file

updating bookmap with nest subtopic structure in a topic file

Re: updating bookmap with nest subtopic structure in a topic file

Re: updating bookmap with nest subtopic structure in a topic file

Re: updating bookmap with nest subtopic structure in a topic file

Re: updating bookmap with nest subtopic structure in a topic file

Re: updating bookmap with nest subtopic structure in a topic file