Topics

Best way for almost identical documents


gdutkowski@...
 

Hi,
I have some software that I am describing and for various reasons there are two dialog boxes that are almost identical, except for a key phrase (A or B for simplicity).
So I want to re-use the task document (or most of it) to describe the processes for creating A and B , but have them differ in only the key phrase.

Looking at some of the options, (keydef etc) they seem to rely on different publishing profiles to be able to produce the task for  either A or B, but not both simultaneously.

I hit on using !ENTITY in the DTD header to define the key phrase (I know this is not recommended) in the top of version A and B and then use conref to copy all of the steps from task version A to task version B.
However my DITA CMS promptly removed the !ENTITY definition when I loaded the file back there.

So, is they some alternative way of doing this that I have not yet hit upon?

Sorry of this has been dealt with before, but I could not find it.

Thanks

Greg.


despopoulos_chriss
 

We have lots of places with similar situations, where different flavors of the product have different small phrases.  We use metadata -- audience for example -- and set up ditavals for each flavor.  It's starting to get complicated because the matrix of differences is extending.  But so far it works!


Chris Papademetrious
 

Hi all,

I feel like it would be useful to be able to include DITAVAL directives inline in the map, instead of in files:

<map>
    <topichead keyscope="NoviceSection" navtitle="Novice Documentation">
        <ditaval>
            <prop att="audience" val="novice" action="include"/>
            <prop att="audience" val="expert" action="exclude"/>
            <dvrResourcePrefix>Novice-</dvrResourcePrefix>
            <dvrKeyscopePrefix>Novice-Scope</dvrKeyscopePrefix>
        </ditaval>
        <mapref format="ditamap" keyref="..."/>
    </topichead>

My thinking is,

  • This allows the branch filtering intent to be visible *and* editable directly where the content is instantiated, instead of requiring side files.
  • DITAVAL used for branch filtering is likely to be single-variable and simple (2-3 directives).

Thoughts?


gdutkowski@...
 

HI,
Thanks for that.
I am not sure that these answers are addressing the problem, although that may be an indication of my ignorance as I don't recognise all of these tags.

Ditavals, as far as I understand, allow you to publish different versions in different outputs through conditional processing.

I want to publish both versions in the same output as both are needed, they are very similar, different in only a few key phrases.
File t_A.dita
<task id="A">
<steps>
<step><cmd>Go to Page A</cmd></step>
<step><cmd>do X,Y,Z</cmd></step>
</steps>
</task>
File t_B.dita
<task id="B">
<steps>
<step><cmd>Go to Page B</cmd></step>
<step><cmd>do X,Y,Z</cmd></step>
</steps>
</task>


Mica Semrick
 


On August 9, 2020 7:15:33 PM PDT, gdutkowski@... wrote:
HI,
Thanks for that.
I am not sure that these answers are addressing the problem, although that may be an indication of my ignorance as I don't recognise all of these tags.

Ditavals, as far as I understand, allow you to publish different versions in different outputs through conditional processing.

I want to publish both versions in the same output as both are needed, they are very similar, different in only a few key phrases.
File t_A.dita
<task id="A">
<steps>
<step><cmd>Go to Page A</cmd></step>
<step><cmd>do X,Y,Z</cmd></step>
</steps>
</task>
File t_B.dita
<task id="B">
<steps>
<step><cmd>Go to Page B</cmd></step>
<step><cmd>do X,Y,Z</cmd></step>
</steps>
</task>


Chris Brand
 

Hi

 

How often do you have this case of almost identical task topics?

 

As a quick shot, I would do the following:

 

  • Create task topic "A" with screenshot "A"
  • Create task topic "B" with screenshot "B" and the key phrase. Conref/Conkeyref everything from "A" that is required. In this case, "A" serves as your toolbox.

 

I understand that filtering is not an option as you need both tasks in the same document, just their content differs in the screenshot and this one key phrase. What I don't understand is the ENTITY thing you tried to do in the DTD for the key phrase. The key phrase is content, right? So what's the idea of messing with the DTD?

 

Greez,

Chris.

 

 

 

Von: main@dita-users.groups.io <main@dita-users.groups.io> Im Auftrag von gdutkowski@...
Gesendet: Donnerstag, 6.
August 2020 02:00
An: main@dita-users.groups.io
Betreff: [dita-users] Best way for almost identical documents

 

Hi,
I have some software that I am describing and for various reasons there are two dialog boxes that are almost identical, except for a key phrase (A or B for simplicity).
So I want to re-use the task document (or most of it) to describe the processes for creating A and B , but have them differ in only the key phrase.

Looking at some of the options, (keydef etc) they seem to rely on different publishing profiles to be able to produce the task for  either A or B, but not both simultaneously.

I hit on using !ENTITY in the DTD header to define the key phrase (I know this is not recommended) in the top of version A and B and then use conref to copy all of the steps from task version A to task version B.
However my DITA CMS promptly removed the !ENTITY definition when I loaded the file back there.

So, is they some alternative way of doing this that I have not yet hit upon?

Sorry of this has been dealt with before, but I could not find it.

Thanks

Greg.


despopoulos_chriss
 

I'm sorry, but I don't know what you mean by publishing both versions in the same output. 

Do you mean that you want an HTML output that contains both versions, but the user chooses which version to read, and the HTML filters out the other version?  We do that, using audience attributes.  We transform on the fly, so that's how we filter.  But you could just as easily convert audience to some class attribute, and then use CSS to show/hide whatever.

But then again, I'm just guessing at what you want.  Can you be more specific?