Feature Request: Show DITA-OT Project File Deliverables in Transformation Scenario List

[chrispitude]

The DITA Maps Manager is the central location where writers work with maps. From there, they add/edit/reorganize topics, validate their books, and run transformations.

When DITA-OT project files are used, the DITA Maps Manager has a great feature that shows DITA-OT project file contexts relevant to the current map. This makes the context/editing aspect of DITA-OT project files easy to configure in the DITA Maps Manager.

It would be great if the DITA Maps Manager could also provide a way to easily run transformations for DITA-OT project file deliverables. One idea is to show relevant DITA-OT project file deliverables as scenarios in the transformation dialog invoked from the DITA Maps Manager:

oxygen_ditaot_project_file_transformations2.png

This would provide the following advantages:

• Deliverables defined across multiple DITA-OT project files (PDF/OLH, review/final, product variants) would be listed in one place.
• It avoids having to browse through many irrelevant deliverables when running the "Publish DITA-OT Project (select deliverable)" transformation directly from a project file.
• It would resolve the largest ease-of-use barrier for writers wanting to adopt DITA-OT project files.

Regarding the list item... Today, DITA-OT project file contexts are easy to work with in day-to-day use. But even being an experienced user, I find it difficult to publish from DITA-OT project files for whatever map I am currently working on.

Ideally, the DITA-OT project files would simply exist in the background as configuration files that allow Oxygen to make everything easy to use. I do not want to actually have to work with DITA-OT project files in day-to-day use. They will be be numerous, long, and likely distributed across directories. (Each repository has 100+ books, with review and final variants of each, and with product profiling conditions on top of that.)

Some aspects to consider:

• If the current context is a .ditamap file, all deliverables publishing that map should probably be listed.
• If the current context is a specific context, the deliverables using that specific context should probably be listed.

oxygen_ditaot_project_file_transformations3.png

A testcase is included:

oxygen_ditaot_project_file_transformations.zip

[Radu]

Hi Chris,

I had an older internal issue kind of similar to what you want, so I renamed it and added your extra feedback on it:

EXM-48744 Present DITA-OT Project deliverables specific for a context and allow running them

For Oxygen 25 we already invested time in adding this more modest alternative/improvement:
If you open a DITA OT project XML file in Oxygen in the "Author" visual editing mode, it will have small "Apply transformation" buttons for each deliverable. You will be able to start and stop a deliverable using that button. If the DITA OT project contains "include"s, they will be expanded in-place in the Author visual editing mode so you will be able to also publish deliverables directly from those included files. You will not be able to start multiple deliverables at once.
It will look something like this:

Screen Shot 2022-06-02 at 07.37.48.png

You will be able to also control the CSS used for visual editing by extending for example the framework we use for DITA OT project file editing, maybe to hide "context" elements completely so that the tech writer only sees deliverables when opening the DITA OT project file.

Regards,
Radu

[chrispitude]

Thanks Radu!

It might be some time before we can use the play button feature, as we use the DITA-OT project file preprocessing (https://blog.oxygenxml.com/topics/prepr ... files.html). But in the future when Oxygen moves to DITA-OT 4.0, then we can use the built-in project file transformations.

Speaking of transformations, I realized that my original request of showing <deliverable> elements in the transformation scenario list did not consider how DITA-OT project file transformations fit into the picture.

For example, consider the case where we define an extended "DITA-OT Project" framework with its own transformations:

image.png

Would Oxygen have to figure out which transformation is the single-deliverable transformation to use for a given deliverable? What if there are multiple single-deliverable transformations?

(I should also mention that my writers would like DITA-OT project transformations to run in the background, as regular transformations do today, so that Oxygen remains usable during publishing.)

[Radu]

Hi Chris,

That play button feature in Oxygen 25 is implemented in the CSS by calling a specific Author operation:

Code: Select all

dp|deliverable[name][id]:before(1) {
  content: oxy_button(action, oxy_action(name, oxy_concat('${i18n(Publish)}', ' ', attr(name)), icon, url('/images/ApplyStyleSheet16.png'), operation, 'ro.sync.ecss.extensions.commons.operations.ExecuteCustomizableTransformationScenarioOperation', arg-scenarioName, 'Publish DITA-OT Project (select deliverable)', arg-scenarioParameters, oxy_concat('deliverable.id=', attr(id)), arg-markOthersInProgressXPathLocation, '//deliverable'), showIcon, true, transparent, true, enableInReadOnlyContext, true);

The "ExecuteCustomizableTransformationScenarioOperation" operation can call any transformation scenario (of type XSLT, ANT, DITA-OT, etc) defined in a framework with a set of custom parameters which will be used in addition to the parameters defined in the transformation scenario.
So it's pretty flexible, you can configure the CSS for a DITA OT project file by extending its framework.

About DITA OT project deliverables and Oxygen transformation scenarios, deliverables indeed are not transformation scenarios, we might show them in the same list and when someone wants to run a deliverable we could dynamically create in our code a transformation scenario specific for it and run it.

Regards,
Radu

[chrispitude]

Hi Radu,

I was able to update that rule to reference the name of our preprocessed version of the DITA-OT Project transformation, and now the publishing button works perfectly! Thank you!!

(And the best part is, running a deliverable transformation using the button runs the transformation in the background!)

Is "ExecuteCustomizableTransformationScenarioOperation" documented somewhere, and is there a similar method for invoking an XSLT refactoring operation by name from a CSS action?

[Radu]

Hi Chris,

The "ExecuteCustomizableTransformationScenarioOperation" is a new operation which will be part of Oxygen 25 (we had to create it in order to make it possible to run such DITA OT project transformation scenarios from the Author page).
It will probably get documented in our user's manual after the Oxygen 25 release:
https://www.oxygenxml.com/doc/ug-editor ... tions.html

About this question:

is there a similar method for invoking an XSLT refactoring operation by name from a CSS action?

Do you mean an XML refactoring operation based on XSLT? Interesting... maybe it would make sens.
We do have a builtin XSLTOperation which can be used to change the current Author document in some way:
https://www.oxygenxml.com/doc/versions/ ... yoperation

Regards,
Radu