Oxygen XML Forum

I'm not understanding the process of setting up a single file that contains related but separate conref items (in my case product names) and then inserting one of those items as a conref in another document. The oXygen documentation skims over the mere capability without giving real-world examples as far as I can tell.

In a previous work environment, using XMetaL, we pulled <ph> references from such a file, but I didn't set the file up and am not sure of the setup/maintenance procedure. Could you give a step-by-step of that setup and of inserting an item from that file into a topic?

This would be a terrific thing to include in the oXygen samples at some point.

Thanks,

Gary

Hi Gary,

What you can do is to create a DITA topic file containing "ph" elements (each "ph" element having as text a product name).

To create such a document you can go to "File" menu and invoke the "New" action. In the filter text field of the dialog that appears type "topic". The DITA Topic template will be selected so, when you press "Create" button, a new DITA Topic document will be created.
In the first paragraph of this document you can add a ph for each product name.

To be able to make a content reference to these product names you have to have an id set for each "ph" element. By default oXygen adds an id for some DITA elements (topic, table, image, etc...), when they are inserted in the document. To do this for ph element also, you can go to "DITA" menu, "ID options..." and in the "ID Options" dialog that appears add the "topic/ph" entry in the "Element name or class value" list.

After you create this topic you can make content references to the "ph" elements containing product names:
- open the topic where you want to insert the reference and place the caret at the position where you want the product name to be inserted
- invoke the "Insert Content Reference" action from the "DITA" menu. The "Insert Content Reference" appears
- choose the URL of the topic containing the product names
- from the targets list select the "ph" that you want to insert
- press OK

Please let me know if you need further assistance.
We will take into account your suggestions and we will try to improve our documentation.

Best Regards,
Mihaela

Thanks for clarifying the procedure, Mihaela. I have a follow-up question:

I put the conref topic file in a separate folder. (We're using SVN as our repository/document management system, BTW, and we use the SVN Client in oXygen). I use a separate folder because I want to have a central file all documents reference for conrefs. But this creates a problem, in that the conref and ID are very long and include the entire path. The conref and ID are bad enough, but when the files are not in the same directory, it's even worse! Perhaps if there were a way to import the conref file by reference into the directory of the topic that contains the conref, that might help, but I wouldn't know how to do this.

Or, is there a way to hide attributes only for <ph> elements? That would eliminate the problem entirely. I'm pretty sure this can be done globally but not sure about selectively. Of course, I could simply turn tags off, but I really prefer working with them on. Barring this, any other suggestions?

Thanks,

Gary

Hope you haven't devoted time to this yet. I found the answer to the question of how to hide attributes, namely that there is a Full Tags option and a Full Tags with Attributes option for displaying in the Editor. I had been using the latter. So obvious! But when you get used to using the product in a certain way, sometimes the obvious becomes not so obvious. In any case, if you have any information about importing files like my conref file by reference into a different directory, that would still be helpful.

Gary

A follow-up question on creating a conref ID file:

Would it work just as well to insert an intelligent ID by hand for each <ph> entry in the conref container file? I'm finding it a little cumbersome searching through the list of <ph> items, which I have inserted into a table in that file to make them easier to read and find. But in the Insert Content Reference dialog, the list displays as meaningless generated IDs.

What would work better would be if the IDs had intelligence, like this example (formatted as code only so the information appears like a table with columns):
Given that the conref ID must be unique every time it is inserted, should this work?

Gary

Hi Gary,

From what I understand you have a topic in which all your small reusable phrases are found, right?

Somebody else asked us a while ago for a quick-find filter in the dialog which allows you to insert conrefs. The quick find would also look in the text content inside the <ph> when searching. So we will consider improving the dialog to better suit such cases.

Recently at a conference I saw another interesting strategy from a technical writer (who was also using Oxygen). Basically his topic file full of reusable phrases had a table with two columns like:
When he wanted to insert a conref, he opened this topic, searched for the description in it and copied the entire phrase from the right column.
Then in the destination file he right clicked and chose "Paste as Content Reference".

Regards,
Radu

Hi,

In Oxygen 15.1 we added a quick find filter to the dialog used to insert conrefs.

Regards,
Radu

Thank you very much!