DITA and XMetaL Discussion

XMetaL Community Forum DITA and XMetaL Discussion Wrestling with Conrefs

  • wetcoastwriter

    Wrestling with Conrefs

    Participants 6
    Replies 7
    Last Activity 13 years, 3 months ago

    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

    Reply to: Wrestling with Conrefs

    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

    Reply to: Wrestling with Conrefs

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

       ..index entries…
       2D Imaging
       

    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

    Reply to: Wrestling with Conrefs

    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

  • in a row 🙂
  • Reply

Derek Read

Reply to: Wrestling with Conrefs

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

Reply to: Wrestling with Conrefs

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

Reply to: Wrestling with Conrefs

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

Reply to: Wrestling with Conrefs

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

  • You must be logged in to reply to this topic.

Lost Your Password?

Products
Downloads
Support