Conref how-to

[gwhite]

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

[mihaela]

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

[gwhite]

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

[gwhite]

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

[gwhite]

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):

Code: Select all

<ph> ID           Definition

prod1-short       Product One

prod1-long        Product One Full Name

prod2-short       Product Two

prod2-long        Product Two Full Name

co-name           My Company Name

Given that the conref ID must be unique every time it is inserted, should this work?

Gary

[Radu]

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:

Code: Select all

<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">

<topic id="topic_a3l_rmv_43">

  <title>Reusable Phrases</title>

  <body>

    <p>

      <table>

        <title>Phrases</title>

        <tgroup cols="2">

          <thead>

            <row>

              <entry>Description</entry>

              <entry>Phrase</entry>

            </row>

          </thead>

          <tbody>

            <row>

              <entry>Description of phrase</entry>

              <entry><ph id="phraseID">the reused content</ph></entry>

            </row>

            .................

          </tbody>

        </tgroup>

      </table>

    </p>

  </body>

</topic>

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

[Radu]

Hi,

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

Regards,
Radu

[gwhite]

Thank you very much!