Feature Request: Have an Oxygen project obtain all profiling condition information from DITAVAL file

[ritus]

Hello,

We generate configuration-specific content. To achieve that, we use profiling heavily.
The profiling conditions vary from product to product. We want the writers to maintain their product-specific profiling settings - attributes, values, and colors. We use subject scheme maps for maintaining the profiling attributes and values. But, currently, profiling colors are defined in the Oxygen .xpr file. It has the following drawbacks:

• The .xpr file must be modified to change color definitions, but writers are not permitted to modify the file.
• A shared .xpr file cannot be used across multiple Oxygen projects that are identical except for their content-specific profiling conditions.
• The color definitions in the .xpr file can become desynchronized with the color definitions in the DITAVAL files.

I understand that one of my colleagues has filed the following enhancement request:

EXM-47205 - Specify in the "Colors and Styles" page a DITAVAL folder used to dynamically load colors

which requests the following:

• In the "Colors and Styles" preferences section, allow a folder to be specified that contains DITAVAL files.
• When Oxygen starts up, dynamically load the color definitions from these files.

This would allow individual writers to maintain their own product-specific DITAVAL files without requiring changes to the .xpr file.

is it possible to have a similar provision for the DITA-OT project file. The context defined in the project file is visible in authoring mode only when we include the DITA-OT project file in the Main Files folder of the .xpr. The project files are product-specific, and writers should be able to maintain their own product-specific project file without requiring changes to the .xpr file.

Thanks,
Ritu

[xephon]

Reusing config chunks between project files would be great. There could be an option, to save/read a specific group of settings from an external config file.

To have another abstraction layer to inherit settings from one project file to another one would also be great.

Because something like this does not exist today, I'm working on a project file generator, which takes a few arguments, such as the context, main files, project directories, and do forth and generates a project file with XSLT. This will be my workaround until the SyncroSoft team hopefully closes this (one of a very few) feature gap.

[Radu]

Thanks for the report Ritu and for the contribution Stefan,

I added an internal issue to consider this:

EXM-50593 Find ways to inherit/share settings between projects

So just to see if I understand Ritu's account, you have a Git repository that everyone checks out, in the repository you have an XPR file which everybody needs to use because it contains common settings.
But technical writers would sometimes change the "Main Files" folder by adding or removing files from there depending on their work, this modifies also the XPR file meaning that they need to be careful not to commit it to the Git repository and from time to time to revert it to the original XPR.
Ritu, is this close to what you are experiencing?

So how could we improve Oxygen to avoid this?
One option would be to able to save the project-related settings to a separate file located next to the XPR. So a "settings.xprs" file located to a "project.xpr". This would mean the Git repo would only distribute the "settings.xprs" and everyone would create their own "project.xpr" (based maybe on a "project_template.xpr" provided in the project) and add it to SVN ignore. All project level settings changed in Oxygen would get saved to the "settings.xprs" file.
Another option as Stefan says would be to leave the original "project.xpr" in the Git repo containing the settings and have each user create their own "project-ext.xpr" which would inherit somehow all settings from the "project.xpr". And the "project-ext.xpr" would be added to Git ignore. But what would happen if the writers modify settings saved already at project level? Would those changes be saved in the "project-ext.xpr" or in the "project.xpr"? Maybe two layers of projects extending each other would prove a challenge to understand.

Regards,
Radu

[chrispitude]

Hi Ritu,

The way I planned on handling this is to add an "all.xml" DITA-OT project file to Main Files that includes all other DITA-OT project files:

image.png (12.33 KiB) Viewed 2883 times

The contents of this "all.xml" file would vary from repo to repo, but the Main Files reference to it in the Oxygen .xpr file would remain identical across repos.

Unfortunately this approach requires writers to manually keep the "all.xml" file up to date as DITA-OT project file components are added/removed. It would be easier if Main Files supported directory references as well as file references, then I could simply include the entire "_project" DITA-OT project file directory in Main Files (with its contents varying from repo to repo).

This solves the inclusion aspect of DITA-OT project files, so that Oxygen scans and understands the contexts/deliverables defined in all DITA-OT project files. However, that does not address the per-writer usability aspect.

For the usability aspect, perhaps the "Favorites" feature described here could be useful:

Have a way to pin/unpin favorite files in the Project view
post58737.html

Then each writer could "favorite" the individual DITA-OT project files that they frequently run transformations for:

image.png (6.85 KiB) Viewed 2883 times

Another usability improvement would be to somehow make DITA-OT project file deliverables relevant to the current map publishable from the DITA Maps Manager. But I am still trying to think through how the UI for that could work.

(I suggest we all refer to "Oxygen project/.xpr file" or "DITA-OT project file" to keep our references unambiguous.)

[Radu]

Hi Chris,

I added a new internal issue for this idea of having an entire folder referenced in the Main Files folder:
EXM-50611 Link to an entire folder in the "Main Files" folder
or maybe as an alternative somehow mark a certain folder in the Project as containing main files.

Regards,
Radu

[chrispitude]

Hi Radu,

Thanks for filing EXM-50611 for Main Files directories! Originally I was concerned about the time it would take to process the files in the directory. But then I realized that for DITA-OT project files, processing the file inclusions of an "all.xml" file requires processing all of those files anyway.

Hi Ritu,

Would the "favorites" feature AND [the "all.xml" DITA-OT project file OR Main Files directory support] provides you with the functionality needed to share a single Oxygen .xpr file across writers/repos? Or would you want/need additional functionality?

Hi xephon,

I had considered writing a similar Oxygen .xpr merging tool, but so far I have been able to avoid it. EXM-47205 (Specify in the "Colors and Styles" page a DITAVAL folder used to dynamically load colors) is the last piece I need to pull all hardcoded profiling conditions out of the Oxygen .xpr file.

Would the "favorites" feature or the Main Files directory support alleviate the need for your Oxygen .xpr file generator? If not, what other types of settings do you have that would vary from one Oxygen environment to another?

[chrispitude]

Regarding the original request in this discussion:

EXM-47205 - Specify in the "Colors and Styles" page a DITAVAL folder used to dynamically load colors

if there is functionality available to beta-test for this feature, I would be happy to test it out!

[Cosmin Duna]

Hi Chris,

Thank you for your interest in testing the beta version.
Unfortunately, we didn't find time to implement this enhancement. I will let you know as soon as we do it.

Best regards,
Cosmin

[chrispitude]

Hi Cosmin,

No problem, there's lots of other good stuff coming in v25. Thanks for the update!

[chrispitude]

We currently have six Git repos (soon to be somewhere between 8-10 repos). In each repo, we store DITAVAL files in the following locations:

• dita/_common/_ditaval/ - identical DITAVAL files across repos (for @rev highlighting, @audience highlighting, etc.)
• dita/_warehouse/_ditaval/ - repo-specific DITAVAL files (for product-specific conditions)

It would be nice if the solution could consider DITAVAL files in multiple folders, perhaps by considering all DITAVAL files found in Main Files (hooray for the Main Files folder support!!). But if the solution considers only a single given path, then perhaps I could specify

Code: Select all

${pd}/dita/_warehouse/_ditaval/

as the path, then place a "common_colors.ditaval" placeholder file there that defines all the common colors.


Hi Ritu,

Are your DITAVAL files all in a single directory, or are they organized across multiple directories?

[chrispitude]

There is a tricky aspect to EXM-47205 when DITA profiling attribute groups are used. Consider the following @product values:

Code: Select all

<p product="synthesis(A)">This is for synthesis product A.</p>
<p product="synthesis(B)">This is for synthesis product B.</p>
<p product="simulation(W)">This is for simulation product W.</p>
<p product="simulation(X)">This is for simulation product X.</p>

When attribute groups are used, the @att attribute in the DITAVAL files refers to the group name, not the attribute name:

Code: Select all

<val>
  <!-- define colors -->
  <prop att="synthesis"  val="A" action="flag" backcolor="#D0E8FF"/>
  <prop att="synthesis"  val="B" action="flag" backcolor="#E8C0FF"/>
  <prop att="simulation" val="W" action="flag" backcolor="#C0FFC0"/>
  <prop att="simulation" val="X" action="flag" backcolor="#FFE8D0"/>
   <!-- ^^^^^^^^^^^^^^^^ -->
</val>

So for Oxygen to import these DITAVAL colors dynamically with no statically stored attribute group information in the .xpr file, then there must be some other way to indicate which groups are associated with which attributes. Radu suggested an Oxygen-specific XML processing instruction, which I think is simple and elegant:

Code: Select all

<val>
  <!-- define the attribute associated with each attribute group -->
  <?oxyProfilingAttribute att="product" groups="synthesis simulation"?>

  <!-- define colors -->
  <prop att="synthesis"  val="A" action="flag" backcolor="#D0E8FF"/>
  <prop att="synthesis"  val="B" action="flag" backcolor="#E8C0FF"/>
  <prop att="simulation" val="W" action="flag" backcolor="#C0FFC0"/>
  <prop att="simulation" val="X" action="flag" backcolor="#FFE8D0"/>
</val>

Radu and I also discussed what precedence behavior should occur when a color is defined in both a dynamically imported DITAVAL file and in the .xpr file. My suggestion was for the DITAVAL file to take precedence, so that the .xpr could provide default behaviors (such as a single color for all @product values), then the DITAVAL files would apply the final writer-maintained intent consistently in both authoring and publishing.

Here is a testcase:

EXM-47205.zip

(6.36 KiB) Downloaded 89 times

OPENME1_atts_defined_in_project.xpr defines the attribute groups and colors statically in the .xpr file in the traditional way, which is how we do it now.

OPENME1.xpr does not define any attribute information in the .xpr file, and instead relies on writer-maintained subject scheme and DITAVAL files (once EXM-47205 is implemented).

[chrispitude]

I see that EXM-47205 has been implemented in Oxygen v26, using the new Automatically apply colors and styles from DITAVAL files referenced in the Main Files folder configuration option:

Oxygen XML documentation > Colors and Styles Preferences

Thanks very much for implementing this! I contributed an Oxygen XML blog post to share our experiences in using it:

Oxygen XML Blog > Converting .xpr Profiling Conditions to Standard DITA Files