Import search file

Are you missing a feature? Request it's implementation here.
jamesW
Posts: 3

Import search file

Tue Jul 07, 2015 7:13 am

Arbortext has this useful feature available from Tools > Search Files > Import Search File.
This feature provides a way to resolve conrefs when each conref specifies the file name that contains the reference, but not a path (relative or absolute) to the conref file. This gives you the flexibility to restructure the files and folders in a documentation project easily.

The way it works is as follows:
1. You open a .dita file in the editor (in this case Oxygen in Author mode).
2. You choose the Import command, and then browse to a DITA Search Path (.dsh) file.
3. The editor then reads all the folders listed in the .dsh file and, for each conref in the .dita file, the editor checks whether the file name that the conref refers to is present in any of the directories listed in the conref file. If the file name is present, the editor resolves the conref in the .dita file, and displays the text that the conref stands for within the keyword element. If the file name is not present, the conref remains unresolved and displays "Error while parsing external reference", exactly as it does now.

The background to this request is that I have some documentation projects that are already set up this way because Arbortext was used as the editor. I like a lot of features in Oxygen and would like to start using it in earnest.
There might be others in in a similar situation who would benefit from this feature.
Radu
Posts: 5211

Re: Import search file

Tue Jul 07, 2015 8:49 am

Hi James,

First of all, I will assume you have the publishing part working in the way that you want (so you only want this for the rendering part).
Second, in my opinion such cases are better handled with using DITA 1.2 conkeyrefs instead of plain conrefs. By indirectly referencing to reusable content using a key, the reusable content file can be moved around without changing references to it.

Now coming back to your problem, we do not have support for this feature but we do have support for XML catalogs.
So here's an alternative for what you had in Arbortext:

1) Let's say you have a folder called reusableTopics.

2) Inside it you have a topic called reusableContent.dita with reusable content inside like:

Code: Select all

<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "http://docs.oasis-open.org/dita/v1.1/OS/dtd/topic.dtd">
<topic id="topicID">
    <title>Introduction</title>
    <body>
        <p id="reusablePara">Some content.</p>
    </body>
</topic>


3) In the same folder you create an XML catalog file named something like catalog.xml with the content:

Code: Select all

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
    <uriSuffix uriSuffix="reusableContent.dita" uri="reusableContent.dita"/>
</catalog>


4) In the Oxygen Preferences->XML / XML Catalog page in the XML catalogs list you add a reference to that XML catalog.

5) Anywhere, in any of your DITA content (in no matter what folder structure) you can now have references like:

Code: Select all

<p conref="reusableContent.dita#topicID/reusablePara"/>


and Oxygen will properly resolve them to the target topic passing through the XML catalog.

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com
jamesW
Posts: 3

Re: Import search file

Wed Jul 08, 2015 4:49 am

Hi Radu,

You are correct that the publishing part is working fine and it was the rendering part I was having trouble with.
I have got a solution to the problem. There is a plugin for Oxygen called IDWB that provides the ability to specify search paths in Preferences > Plugins > IDWB Options > DITA Search Path Options.
I did also try creating a sample project with a reusableContent.dita file and a catalog.xml file, following your steps but I couldn't get my conref to reusableContent.dita#topicID/reusablePara to resolve correctly. It seemed to be looking in the wrong folder for reusableContent.dita.
I believe this is probably because the IDWB plugin (that you couldn't have known about) was overriding catalog.xml.
Thank you very much for your help. :D The catalog method might prove to be a useful alternative in the future.

James
Radu
Posts: 5211

Re: Import search file

Wed Jul 08, 2015 8:49 am

Hi James,

There is a plugin for Oxygen called IDWB that provides the ability to specify search paths in Preferences > Plugins > IDWB Options > DITA Search Path Options.


Great, I did not know that. If the plugin is open source and if you can give me a link to it I will add it to our list of public hosted Oxygen plugins and frameworks:

http://blog.oxygenxml.com/2014/11/public-hosted-oxygen-plugin-and.html

I did also try creating a sample project with a reusableContent.dita file and a catalog.xml file, following your steps but I couldn't get my conref to reusableContent.dita#topicID/reusablePara to resolve correctly. It seemed to be looking in the wrong folder for reusableContent.dita.
I believe this is probably because the IDWB plugin (that you couldn't have known about) was overriding catalog.xml.


I'm not sure, that might be the problem. I tested the steps I gave you before posting them so they should work.
You also need to make sure that when the catalog file refers to the target like:

Code: Select all

 <uriSuffix uriSuffix="...." uri="reusableContent.dita"/>


that target file needs to be located relative to the XML catalog.

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com
jamesW
Posts: 3

Re: Import search file

Wed Jul 08, 2015 10:03 am

Hi Radu,
Unfortunately the plugin is proprietary so we can't add it to that list.
I checked my catalog.xml. It is in the same folder as my reusableContent.dita, and it's an exact copy of your catalog.xml.
Anyhow, for my part, all is well and I have a solution.
Thanks again
James
Sangeeta
Posts: 10

Re: Import search file

Tue Jan 09, 2018 5:53 pm

Hi Radu,

I have content references of type:
<ph conref="ptcProduct.dita#ptcProduct/WCQMSCAPA"></ph>.

I have created catalog.xml file in the folder where product.dita resides. The references are seen in oXygen editor, however, when I generate the output the references are not resolved. Can you please help?

catalog.xml

log xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
<uriSuffix uriSuffix="ptcProduct.dita" uri="ptcProduct.dita"/>
</catalog>

Second question, I have around 2-3 conrent reference files in different folders. Can I move all of them to one folder, and create a single catalog.xml file listing all the *.dita files that contain conrefs?

Best regards,
Sangeeta
Radu
Posts: 5211

Re: Import search file

Wed Jan 10, 2018 9:35 am

Hi,

In order not to duplicate answers I will answer you separately on the new thread you opened:

https://www.oxygenxml.com/forum/viewtopic.php?f=1&t=15388&p=45274#p45274

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

Return to “Feature Request”

Who is online

Users browsing this forum: No registered users and 1 guest