In a large dita document set, can someone explain how to associate a unique profile condition set with each ditamap?
-
rwmm415
- Posts: 5
- Joined: Mon May 15, 2023 7:23 pm
In a large dita document set, can someone explain how to associate a unique profile condition set with each ditamap?
In Brief: I am looking for an automatic way to bind a unique conditional profile to each ditamap in a set of related maps.
We publish several versions of a large technical user guide in Oxygen. All of the dita content (thousands of files) resides in a single directory. The make up of each version of the guide is determined by its ditamap. A large percentage of the dita files are shared between the versions. Some of the shared dita contains conditional profiling to customize the content to the document's "context" when it's necessary to do so. All of this is already implemented and it seems to work well for both PDF and WebHelp build scenarios.
What I don't like about the current setup is that each time a ditamap is opened for one of the guide versions, the writer has to remember to use the Oxy menu commands to select the appropriate profile condition set for that version of the guide. If the the wrong condition set (or none) is selected you'll get incorrect display of content in editor Author mode and incorrect build results. I generally remember to check this when I open a new map, but that's because I set this system up in the first place. The other writers and maintainers are unclear on why this matters and often forget to do it. They'll get these problems, forget to check the profile setting and then contact me. I am seeking an AUTOMATIC way to bind the proper condition set to each ditamap -- surely, there's got to be a way to do this.
Let me quickly run through the methods I have tried already:
CONFIGURING A FILTER IN THE TRANSFORM SCENARIO. Yes, you can specify a 'ditaval' file on the filter tab so that the proper profile conditions are set at build time. This requires creating multiple duplicate scenarios that differ only in the ditaval selection -- though this can probably be avoided by having a single scenario with a ditaval selection specified using a substitution editor variable in the filename. (I haven't tried this yet.) However, the shortcoming of this approach is that the condition set is not established in the Oxy editor so that the writers don't get the benefit of a WYSIWG view that reflects the current profiling conditions. So, this method is not a complete solution.
PROFILING CONDITION SETS SAVED IN A PROJECT FILE (XPR). It is often suggested that you can save profiling condition sets into the project file to ensure they are automatically associated with the maps in that specific project. Yes, the project file retains all possible condition settings (Product=[EUR/ASIA/NA] in this case) and whatever selection was the last used in the project. But all versions of our user guide are part of a common project. Having multiple project files would require the writer to switch between them to work on different versions of the user guide. This would be no less of a burden than remembering to select the profile condition set when opening a user guide map (what we currently do).
BRANCH FILTERING. This approach (embedding a <DITVALREF> in the map) is the one that ought to do exactly what we need -- associate a condition set with a ditamap. It fails for us in two ways. First, you can't apply the <ditavalref> tag at the root level of the map. Each of our guides is defined as a <bookmap> containing a list of <parts>. The bookmap won't accept a <ditavalref> tag, so that forces you to apply them to the individual <part> sections. This is a minor bit of redundancy and I can live with it.
The bigger problem occurs during the build. The transform generates thousands of duplicate topic ID errors (a pair of errors for every topic ID in the guide, apparently). I read another post in this forum that suggests this is an artifact, a result of the way that conditional profiling is implemented in Oxygen. The build should succeed anyway and the errors can be ignored. But we have repeatedly tried to emphasize to our writers the importance of having "clean", zero-error builds when publishing, and to stop the practice of ignoring the error logs. So, we would like to avoid this approach if possible.
EXPRESSING PROFILE CONDITION SETS AS DITAVAL. One final concern I've wondered about: Have I formatted my ditaval correctly? You can import ditaval files in Oxy to apply their profile condition settings, but you can't export your current profile to ditaval, AFAIK. You're on own to construct a ditaval file that is equivalent to the current profile setting. Our use of profiling is quite simple. We use the predefined 'product' attribute and have given it the possible values: [EUR/ASIA/NA]. So, for example, if I select the EUR profile through the menu command, it sets the condition 'product = EUR'. Based on examples I could find online, I have tried to express this setting in a ditaval file as follows, though I still not certain this is correct.
<?xml version="1.0" ?>
<val>
<prop action="exclude" att="product"></prop>
<prop action="include" att="product" val="EUR"></prop>
</val>
In summary, the two questions are:
(1) How can I automatically bind unique condition sets to each ditamap in a set of related maps on opening?
(2) Have I expressed the simple "product=[ A | B | C ]" condition setting correctly as ditaval XML in the example shown above?
Best regards,
Robert @ Hoffman MarCom
We publish several versions of a large technical user guide in Oxygen. All of the dita content (thousands of files) resides in a single directory. The make up of each version of the guide is determined by its ditamap. A large percentage of the dita files are shared between the versions. Some of the shared dita contains conditional profiling to customize the content to the document's "context" when it's necessary to do so. All of this is already implemented and it seems to work well for both PDF and WebHelp build scenarios.
What I don't like about the current setup is that each time a ditamap is opened for one of the guide versions, the writer has to remember to use the Oxy menu commands to select the appropriate profile condition set for that version of the guide. If the the wrong condition set (or none) is selected you'll get incorrect display of content in editor Author mode and incorrect build results. I generally remember to check this when I open a new map, but that's because I set this system up in the first place. The other writers and maintainers are unclear on why this matters and often forget to do it. They'll get these problems, forget to check the profile setting and then contact me. I am seeking an AUTOMATIC way to bind the proper condition set to each ditamap -- surely, there's got to be a way to do this.
Let me quickly run through the methods I have tried already:
CONFIGURING A FILTER IN THE TRANSFORM SCENARIO. Yes, you can specify a 'ditaval' file on the filter tab so that the proper profile conditions are set at build time. This requires creating multiple duplicate scenarios that differ only in the ditaval selection -- though this can probably be avoided by having a single scenario with a ditaval selection specified using a substitution editor variable in the filename. (I haven't tried this yet.) However, the shortcoming of this approach is that the condition set is not established in the Oxy editor so that the writers don't get the benefit of a WYSIWG view that reflects the current profiling conditions. So, this method is not a complete solution.
PROFILING CONDITION SETS SAVED IN A PROJECT FILE (XPR). It is often suggested that you can save profiling condition sets into the project file to ensure they are automatically associated with the maps in that specific project. Yes, the project file retains all possible condition settings (Product=[EUR/ASIA/NA] in this case) and whatever selection was the last used in the project. But all versions of our user guide are part of a common project. Having multiple project files would require the writer to switch between them to work on different versions of the user guide. This would be no less of a burden than remembering to select the profile condition set when opening a user guide map (what we currently do).
BRANCH FILTERING. This approach (embedding a <DITVALREF> in the map) is the one that ought to do exactly what we need -- associate a condition set with a ditamap. It fails for us in two ways. First, you can't apply the <ditavalref> tag at the root level of the map. Each of our guides is defined as a <bookmap> containing a list of <parts>. The bookmap won't accept a <ditavalref> tag, so that forces you to apply them to the individual <part> sections. This is a minor bit of redundancy and I can live with it.
The bigger problem occurs during the build. The transform generates thousands of duplicate topic ID errors (a pair of errors for every topic ID in the guide, apparently). I read another post in this forum that suggests this is an artifact, a result of the way that conditional profiling is implemented in Oxygen. The build should succeed anyway and the errors can be ignored. But we have repeatedly tried to emphasize to our writers the importance of having "clean", zero-error builds when publishing, and to stop the practice of ignoring the error logs. So, we would like to avoid this approach if possible.
EXPRESSING PROFILE CONDITION SETS AS DITAVAL. One final concern I've wondered about: Have I formatted my ditaval correctly? You can import ditaval files in Oxy to apply their profile condition settings, but you can't export your current profile to ditaval, AFAIK. You're on own to construct a ditaval file that is equivalent to the current profile setting. Our use of profiling is quite simple. We use the predefined 'product' attribute and have given it the possible values: [EUR/ASIA/NA]. So, for example, if I select the EUR profile through the menu command, it sets the condition 'product = EUR'. Based on examples I could find online, I have tried to express this setting in a ditaval file as follows, though I still not certain this is correct.
<?xml version="1.0" ?>
<val>
<prop action="exclude" att="product"></prop>
<prop action="include" att="product" val="EUR"></prop>
</val>
In summary, the two questions are:
(1) How can I automatically bind unique condition sets to each ditamap in a set of related maps on opening?
(2) Have I expressed the simple "product=[ A | B | C ]" condition setting correctly as ditaval XML in the example shown above?
Best regards,
Robert @ Hoffman MarCom
-
Radu
- Posts: 9616
- Joined: Fri Jul 09, 2004 5:18 pm
Re: In a large dita document set, can someone explain how to associate a unique profile condition set with each ditamap?
Hello Robert,
I would advise you to take a look at this DITA OT Project file configuration:
https://www.oxygenxml.com/doc/versions/ ... oject.html
As per this example from the Oxygen User's Manual Git project you define pairs, associations of DITA Maps and filter:
https://github.com/oxygenxml/userguide/ ... roject.xml
Besides defining such associations you can also define deliverables for each publication and then publish directly a DITA OT project file instead of publishing using Oxygen transformation scenarios:
https://www.oxygenxml.com/doc/versions/ ... _file.html
Once you define in an Oxygen Project a DITA OT project file, you can enable the "Main Files" support and add to the "Main Files" folder a reference to the DITA OT project file:
https://www.oxygenxml.com/doc/versions/ ... files.html
Afterwards in the DITA Maps Manager view the "Context" drop down combo box will allow you to pick from the pairs of contexts defined in the DITA OT project file, each map + ditaval context applying the profiling when it is selected.
Please see some more remarks below:
Yes, transformation scenarios would only fix the publishing side of things.
https://github.com/orgs/dita-ot/discussions/4282
For the Oxygen User's guide we seem to have chosen using an explicit way of filtering but yours is more compact:
https://github.com/oxygenxml/userguide/ ... sa.ditaval
Regards,
Radu
I would advise you to take a look at this DITA OT Project file configuration:
https://www.oxygenxml.com/doc/versions/ ... oject.html
As per this example from the Oxygen User's Manual Git project you define pairs, associations of DITA Maps and filter:
https://github.com/oxygenxml/userguide/ ... roject.xml
Besides defining such associations you can also define deliverables for each publication and then publish directly a DITA OT project file instead of publishing using Oxygen transformation scenarios:
https://www.oxygenxml.com/doc/versions/ ... _file.html
Once you define in an Oxygen Project a DITA OT project file, you can enable the "Main Files" support and add to the "Main Files" folder a reference to the DITA OT project file:
https://www.oxygenxml.com/doc/versions/ ... files.html
Afterwards in the DITA Maps Manager view the "Context" drop down combo box will allow you to pick from the pairs of contexts defined in the DITA OT project file, each map + ditaval context applying the profiling when it is selected.
Please see some more remarks below:
With the DITA OT Project approach, when one opens a top level DITA Map they would also need to select in the Context combo box the context map+ditaval mapping for it.In Brief: I am looking for an automatic way to bind a unique conditional profile to each ditamap in a set of related maps.
Sometimes one can use keys and key references to achieve results similar to using profiling conditions. For example each DITA Map could define the same key but bind it to a different value.We publish several versions of a large technical user guide in Oxygen. All of the dita content (thousands of files) resides in a single directory. The make up of each version of the guide is determined by its ditamap. A large percentage of the dita files are shared between the versions. Some of the shared dita contains conditional profiling to customize the content to the document's "context" when it's necessary to do so. All of this is already implemented and it seems to work well for both PDF and WebHelp build scenarios.
I agree, with a DITA OT project file one defines all deliverables inside (each deliverable being similar to a transformation scenario) and one can publish either one deliverable or publish them all.CONFIGURING A FILTER IN THE TRANSFORM SCENARIO. Yes, you can specify a 'ditaval' file on the filter tab so that the proper profile conditions are set at build time. This requires creating multiple duplicate scenarios that differ only in the ditaval selection -- though this can probably be avoided by having a single scenario with a ditaval selection specified using a substitution editor variable in the filename. (I haven't tried this yet.) However, the shortcoming of this approach is that the condition set is not established in the Oxy editor so that the writers don't get the benefit of a WYSIWG view that reflects the current profiling conditions. So, this method is not a complete solution.
Yes, transformation scenarios would only fix the publishing side of things.
OkPROFILING CONDITION SETS SAVED IN A PROJECT FILE (XPR). It is often suggested that you can save profiling condition sets into the project file to ensure they are automatically associated with the maps in that specific project. Yes, the project file retains all possible condition settings (Product=[EUR/ASIA/NA] in this case) and whatever selection was the last used in the project. But all versions of our user guide are part of a common project. Having multiple project files would require the writer to switch between them to work on different versions of the user guide. This would be no less of a burden than remembering to select the profile condition set when opening a user guide map (what we currently do).
I would advise you against using ditavalref, indeed it cannot be referenced on the first level in the Bookmap (this will be fixed I think in the DITA 2.0 standard). But furthermore there are various publishing bugs associated to ditavalrefs:BRANCH FILTERING. This approach (embedding a <DITVALREF> in the map) is the one that ought to do exactly what we need -- associate a condition set with a ditamap. It fails for us in two ways. First, you can't apply the <ditavalref> tag at the root level of the map. Each of our guides is defined as a <bookmap> containing a list of <parts>. The bookmap won't accept a <ditavalref> tag, so that forces you to apply them to the individual <part> sections. This is a minor bit of redundancy and I can live with it.
https://github.com/orgs/dita-ot/discussions/4282
Can you paste an example or screenshot with how these errors look like?The bigger problem occurs during the build. The transform generates thousands of duplicate topic ID errors (a pair of errors for every topic ID in the guide, apparently). I read another post in this forum that suggests this is an artifact, a result of the way that conditional profiling is implemented in Oxygen. The build should succeed anyway and the errors can be ignored. But we have repeatedly tried to emphasize to our writers the importance of having "clean", zero-error builds when publishing, and to stop the practice of ignoring the error logs. So, we would like to avoid this approach if possible.
The ditaval you defined looks good, I agree it is more technical but not everybody needs to define the ditaval, just use it as it is.EXPRESSING PROFILE CONDITION SETS AS DITAVAL. One final concern I've wondered about: Have I formatted my ditaval correctly? You can import ditaval files in Oxy to apply their profile condition settings, but you can't export your current profile to ditaval, AFAIK. You're on own to construct a ditaval file that is equivalent to the current profile setting. Our use of profiling is quite simple. We use the predefined 'product' attribute and have given it the possible values: [EUR/ASIA/NA]. So, for example, if I select the EUR profile through the menu command, it sets the condition 'product = EUR'. Based on examples I could find online, I have tried to express this setting in a ditaval file as follows, though I still not certain this is correct.
<?xml version="1.0" ?>
<val>
<prop action="exclude" att="product"></prop>
<prop action="include" att="product" val="EUR"></prop>
</val>
As mentioned above I would not use ditaval ref, besides the various publishing bugs Oxygen's UI also does not take them into account when presenting filtered content in the editor area.In summary, the two questions are:
(1) How can I automatically bind unique condition sets to each ditamap in a set of related maps on opening?
Yes, so you have an exclude all product attribute values filter followed by an inclusion of a specific value.(2) Have I expressed the simple "product=[ A | B | C ]" condition setting correctly as ditaval XML in the example shown above?
For the Oxygen User's guide we seem to have chosen using an explicit way of filtering but yours is more compact:
https://github.com/oxygenxml/userguide/ ... sa.ditaval
Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com
<oXygen/> XML Editor
http://www.oxygenxml.com
-
rwmm415
- Posts: 5
- Joined: Mon May 15, 2023 7:23 pm
Re: In a large dita document set, can someone explain how to associate a unique profile condition set with each ditamap?
Wow, Radu. Thanks! That's a lot to take in.
Let me play with this for a bit and get back here with a report and/or follow up questions.
Best, Robert
Let me play with this for a bit and get back here with a report and/or follow up questions.
Best, Robert
-
Radu
- Posts: 9616
- Joined: Fri Jul 09, 2004 5:18 pm
Re: In a large dita document set, can someone explain how to associate a unique profile condition set with each ditamap?
Hello Robert,
I will delete your last two messages as per instructions, about the person-to-person tone, I'd rather enjoy keeping it
Our support email address is (support@oxygenxml.com) if you do not want to use the forum.
As a side note, Oxygen 25 is in our end of life stage so officially we no longer support it or offer security updates for it: https://www.oxygenxml.com/eol.html
You seem to have successfully set up the DITA OT project file (no need to define extra deliverables inside if not necessary) in the Oxygen "Main Files" folder. Indeed this adds the contexts to the "DITA Maps Manager" "Context" combo box. This particular combo box controls only the resolution of keys and applying of profiling conditions which come with a particular applied context, it does not control the actual DITA Map opened in the DITA Maps Manager view, the user would still need to open the right DITA Map. I'm sorry I do not have a solution right now which perfectly would resolve your situation.
Regards,
Radu
I will delete your last two messages as per instructions, about the person-to-person tone, I'd rather enjoy keeping it
Our support email address is (support@oxygenxml.com) if you do not want to use the forum.
As a side note, Oxygen 25 is in our end of life stage so officially we no longer support it or offer security updates for it: https://www.oxygenxml.com/eol.html
You seem to have successfully set up the DITA OT project file (no need to define extra deliverables inside if not necessary) in the Oxygen "Main Files" folder. Indeed this adds the contexts to the "DITA Maps Manager" "Context" combo box. This particular combo box controls only the resolution of keys and applying of profiling conditions which come with a particular applied context, it does not control the actual DITA Map opened in the DITA Maps Manager view, the user would still need to open the right DITA Map. I'm sorry I do not have a solution right now which perfectly would resolve your situation.
Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com
<oXygen/> XML Editor
http://www.oxygenxml.com