Topics

Confused with Profiling and Ditaval #Oxygen #reuse

Matt Lorenzi
 

I thought I could finally take a deeper dive into single sourcing, but I'm getting conflicted with the approach I should use. I am using Oxygen XML Author.

I have three product manuals, and I am using three different maps - so far so good. Much of the content is shared, so those topics are pulling from a common folder via conref.

I have one topic that is 99% shared by all three, but in each variant I want to show a different image. So this is where I get confused. What is the best approach to use?
Do I insert all three images into the topic and then attach a profiling attribute to them? Would I define three product attribute values, then define which one to use in my map? How then do I select which one to use on output? 

I think this is where I get stumped: is this is is a DITAval situation, or a Profile Condition Set situation, or neither? Again, I am using three maps, not trying to build three manuals from one map. So maybe I am overthinking this?

This may be easy stuff, but I've done very little single sourcing to date. I've done the Learning Dita courses, and while helpful I could use some in depth Oxygen training to really get me going (hint, hint).


Radu Coravu
 

Hi Matt,

One option is indeed to have three image references in the topic, each with a different profiling attribute value and filter using the DITAVAL filters.

Another option is to use a keyref for the image:

<image keyref="imageKey"/>

and define in each published DITA Map the same key name bound to a different resource, like:

<keydef keys="imageKey" href="path/to/image.png" format="png"/>

Regards,
Radu
Radu Coravu
Oxygen XML Editor
On 5/28/20 3:26 AM, Matt Lorenzi via groups.io wrote:

I thought I could finally take a deeper dive into single sourcing, but I'm getting conflicted with the approach I should use. I am using Oxygen XML Author.

I have three product manuals, and I am using three different maps - so far so good. Much of the content is shared, so those topics are pulling from a common folder via conref.

I have one topic that is 99% shared by all three, but in each variant I want to show a different image. So this is where I get confused. What is the best approach to use?
Do I insert all three images into the topic and then attach a profiling attribute to them? Would I define three product attribute values, then define which one to use in my map? How then do I select which one to use on output? 

I think this is where I get stumped: is this is is a DITAval situation, or a Profile Condition Set situation, or neither? Again, I am using three maps, not trying to build three manuals from one map. So maybe I am overthinking this?

This may be easy stuff, but I've done very little single sourcing to date. I've done the Learning Dita courses, and while helpful I could use some in depth Oxygen training to really get me going (hint, hint).




  

John Piechowski
 

Matt,

As Radu points out, there are two different options here and we struggled deciding the best approach, so I thought I would share the decision process we used.

As we looked at our content we realized that as our topics evolved we would likely grow from [3 in your example] images in a topic to 4, then 5, and so on as we added more products using the same topic.

While DITAVAL could definitely work, it seemed like managing more than 3 or 4 images with filters in a single topic could become difficult for the author. It would be a lot of noise in the topic compared to the actual content.

So we decided that we would keep DITAVAL use to a high level product category and audience, and use conkeyrefs with an "image warehouse" for your example. The author builds up their images for the manual in a separate topic that is keyrefed in. That way the topic stays primarily as content, but we can swap in any image we want.

For us, this approach has worked very well.

Matt Lorenzi
 

So looks like there's a few avenues here. So rather a a master topic for the image, I'd create one for each image? That would resolve the single sourcing issue, but less so if I want to reuse the text and image in another map -  would always have to make sure I grabbed both topics. 

So I could use a keyref for the image placeholder, then call up the image in my map? Is that what you mean Radu? Is there more scripting involved than you you provided above? I'm oddly excited to try this.

Larry Kollar
 

Two of my co-workers have a set of topics shared by literally dozens of products, and different mainly in what image gets loaded. They use conkeyrefs, with different bookmap and key files for each products. I've lately adopted the scheme for my own docs, although the differences are primarily in product groups, so I only have two (maybe three, tops) images to choose from.

Radu Coravu
 

Hi Matt,

When it comes to reusing images using keys there are two possible approaches:

1) Create a DITA map named something like "imageKeys.ditamap" with lots of keydefs like:

 <keydef keys="image1" href="image1.png" format="png"/>
  <keydef keys="image2" href="image2.png" format="png"/>
Refer to this "imageKeys.ditamap" in the main product.ditamap.

From each topic use:

<image keyref="imageKey"/>
to refer to images.

2) Create an "images.dita" topic which lost of image references, each image reference with an @id.

The content of the "images.dita" would look like:

<topic id="images">
    <title>Images</title>
    <body>
        <image href="image1.png" alt="image 1 text" id="image1"/>
        <image href="image2.png" alt="image 2 text" id="image2"/>
.........
    </body>
</topic>
The "images.dita" would be referenced in the main product.ditamap as a resource only topic so that it does not appear in the output and assigned a key:
<keydef keys="images" href="images.dita"/>
and then each topic would use conkeyefs to refer to images like:

<image conkeyref="images/image1"/>

Approach (2) does have certain upsides, you can reuse also the image alternate texts. You can also reuse also entire <fig> figure elements.


Regards,

Radu

Radu Coravu
Oxygen XML Editor
On 5/29/20 11:14 PM, Matt Lorenzi via groups.io wrote:

So looks like there's a few avenues here. So rather a a master topic for the image, I'd create one for each image? That would resolve the single sourcing issue, but less so if I want to reuse the text and image in another map -  would always have to make sure I grabbed both topics. 

So I could use a keyref for the image placeholder, then call up the image in my map? Is that what you mean Radu? Is there more scripting involved than you you provided above? I'm oddly excited to try this.



  

John Piechowski
 

We use option 2, an image topic that we add into our ditamap as a key.

John

On Sun, May 31, 2020, 12:28 AM Radu Coravu <radu_coravu@...> wrote:

Hi Matt,

When it comes to reusing images using keys there are two possible approaches:

1) Create a DITA map named something like "imageKeys.ditamap" with lots of keydefs like:

 <keydef keys="image1" href="image1.png" format="png"/>
  <keydef keys="image2" href="image2.png" format="png"/>
Refer to this "imageKeys.ditamap" in the main product.ditamap.

From each topic use:

<image keyref="imageKey"/>
to refer to images.

2) Create an "images.dita" topic which lost of image references, each image reference with an @id.

The content of the "images.dita" would look like:

<topic id="images">
    <title>Images</title>
    <body>
        <image href="image1.png" alt="image 1 text" id="image1"/>
        <image href="image2.png" alt="image 2 text" id="image2"/>
.........
    </body>
</topic>
The "images.dita" would be referenced in the main product.ditamap as a resource only topic so that it does not appear in the output and assigned a key:
<keydef keys="images" href="images.dita"/>
and then each topic would use conkeyefs to refer to images like:

<image conkeyref="images/image1"/>

Approach (2) does have certain upsides, you can reuse also the image alternate texts. You can also reuse also entire <fig> figure elements.


Regards,

Radu

Radu Coravu
Oxygen XML Editor
On 5/29/20 11:14 PM, Matt Lorenzi via groups.io wrote:

So looks like there's a few avenues here. So rather a a master topic for the image, I'd create one for each image? That would resolve the single sourcing issue, but less so if I want to reuse the text and image in another map -  would always have to make sure I grabbed both topics. 

So I could use a keyref for the image placeholder, then call up the image in my map? Is that what you mean Radu? Is there more scripting involved than you you provided above? I'm oddly excited to try this.



  

ronny.flink@...
 

Hi,
I started working with reuse by adding all images for a reuse topic and then filter using profiling attributes.
I have since then moved away from this way of working with images and instead only add an image with a keyref and then define the key in the products root map. This is much easier to maintain and saves a lot of work.

Oxygen has a good video on this:

https://m.youtube.com/watch?v=NNtaRR4nbD8&t=3898s 

Best regards
Ronny

Matt Lorenzi
 

Thanks to everyone. Will check out the webinar now. Going to be a student today!