Wrestling with Conrefs

[wetcoastwriter]

Now that we are staying out of our CMS and working in a shared file structure, we're going to go ahead with our plans for conrefs.
We have three basic types of conrefs we want to use:
– steps that vary between products
– concepts that vary between products
– admonitions (notes, warnings, and cautions with standard text across products)
I managed to test replacing a series of steps with a conref and got the output I expected. I did have to do some work in the conref generated by XMetal (Reuse > Create Reusable Component) but it allows me to have a series of steps in the conref.
When trying to do a similar thing with a series of paragraphs, the component originally placed the selected paragraphs into a ph element… which is not legal and XMetal complained bitterly about. If I remove the ph element and have a series of paragraphs in the component, I get empty paragraphs in my topic.
How do I put a series of paragraphs into a conref?

Reply

[Derek Read]

The conref attribute must be set on an element (yes, that's pretty obvious), so in order to include a group of elements together they must be included within a parent element where the conref attribute is set. To group a number of paragraphs together you will need to wrap them in another legally allowed element and then set the conref on that element. This includes the following, which are possibly the most logical choices (though this really depends very highly on your content):

section
example
note
lq
body

There are many other elements you could use depending on the topic type and the context. To find a full list of all parent elements that can contain

right click in a

element and select “Help on Current Element”. That will open the DITA Language Reference and take you to the help for

. The “Contained by” section lists all possible parents for

.

Reply

[wetcoastwriter]

Hmm, ok.
So in the topic I have something like this:

   ..index entries…
   
   

text about 2D imaging that pertains to all products

   

product A text

   

more product A text

   

product B text

      

product C text

So, to do what you're suggesting I would replicate the section for each product, rather than trying to have a single section with a series of product-specific conrefs…

Please correct me if I'm wrong.

— New Question —
Is there a template for a reusable component? I'd like to be able to create them without having to parse them *from* content.

Thanks,
Wanda

Reply

[ghkrause]

Wanda,
The reusable component is an XMetaL thing that can be made usable for any schema or DTD – this is older than DITA! For DITA the conref mechanism is achieving the same but with other means. The current spec 1.1 is limited to single element reuse (a section with many p elements as contents is such a single element). The new DITA spec 1.2 supports conref ranges to reuse step 3 to 5 out of 8 steps of a task for example. Support of DITA 1.2 is not yet announced as far as I know.
Therefore: either conref each element of a sequence on its own by adding an id attribute value to the source elements (you may rename the GUID based autogenerated IDs to speaking names like “myPara01”, but stick to XML rules of NMTOKEN or ID). Then you can insert a conref via menu in XMetaL 5.1 or 5.5.
You are not the only one that does not like to do 10 conref insertions for 10

or

[Derek Read]

You can create your own templates for any type of document. If you place an XML document into the Template folder structure it will be listed inside the New from Template dialog.

Note that any content you include in a template is preserved inside any new documents based on that template. This includes id attr values, so for DITA you will want to remove them from any templates you create.

Reply

[Su-Laine Yeo]

As Gunnar said above, you can't have a conref that spans multiple paragraphs in DITA 1.1, and using reusable components won't solve this limitation. Your best bet is probably to conref in each paragraph one at at time. For the example above with product A, B, and C, you could also use conditional text, but I'm sure you've already thought of that.

If you still want to create a template for creating reusable components, this post provides additional detail to what Derek said: http://forums.xmetal.com/index.php?topic=284.0

Reply

[wetcoastwriter]

Hi Su-Laine,
The idea of creating and linking conrefs for every para is kind of akin to sticking pencils into our eyes. Yuck.
Working with conditional text has gotten way too complicated for two reasons. First, the topics themselves are getting huge and very colourful. Second, writers may need to lock a topic for a product release and another product release, that uses the topic, may be in production. We don't want the entire topic locked out.
We're trying to make the content more flexible. We're in a situation where multiple writers may touch a topic, and some of those writers work off-site. We can't have topics locked up and unavailable when the topic is applied to up to 6 products.
Plus, while writer A is adding content to the topic writer B may be needing to do comment incorporation.
We don't want to spend hours replicating topics and maps for books as the overall structure is very standard.
So, we're experimenting with creating reuseable components with the entire section (section tags, index entries, title, and then product-specific content).
The writers work in the reuseable component, so even if they have the live copy locked, the topic itself can be compiled.

Reply

[Su-Laine Yeo]

Hi Wanda,

DITA 1.2 will address the situation you're describing. DITA 1.2 has many enhancements to conref functionality that you would find useful. Alas, it's still quite a few months away.

A strategy that I just thought of is to create a specialization or an outputclass of the element, and use that as a wrapper around multiple paragraphs. You would have to change your stylesheets so that that specialization or outputclass of doesn't have the formatting that a would normally have.

Then you can conref the into your topic. You can put text, paragraphs, lists, images, and tables into a element. However, a limitation that might kaibosh the whole strategy is that you can't put another inside a .

Su-Laine

Reply

[Author]

Posts