Automatically generating task labels (stepxmp, stepresult)

[Bas10R]

Hello,

I'm using Oxygen XML Editor v25.1, with a project based on the ootb startup project.
I've enabled the "args.gen.task.lbl" parameter, which generates the majority of task labels. Unfortunately, the output doesn't generate labels for <stepxmp> and <stepresult> elements.

I'm aware such text can be added via CSS, but the resulting output isn't selectable and readable via screen readers (therefore against my company's localization and accessibility guidelines,) so I want to display these labels in the same way that labels such as "About this task" (<context>), "Results" (<result>), or "What to do next" (<postreq>) are displayed.

Kind regards,
Konrad

[Radu]

Hi Konrad,
Are you publishing to PDF (CSS based on XSL-FO based) or WebHelp?
For some DITA task elements the DITA OT stylesheets do not generate any labels.
You can look in the stylesheet "OXYGEN_INSTALL_DIR/frameworks/dita/DITA-OT/plugins/org.dita.html5/xsl/task.xsl"
There is a template which matches:

Code: Select all

 <xsl:template match="*[contains(@class,' task/stepxmp ')]" name="topic.task.stepxmp">
    <xsl:call-template name="generateItemGroupTaskElement"/>
  </xsl:template>

and also a "mode="generate-task-label"" in which for certain elements the label is generated. I cannot precisely state why for certain elements the decision was taken not to present labels before them.
The label variables are defined here:
OXYGEN_INSTALL_DIR/frameworks/dita/DITA-OT/plugins/org.dita.base/xsl/common/strings-en-us.xml

Code: Select all

   <variable id="task_context">About this task</variable>
   <variable id="task_example">Example</variable>
   <variable id="task_postreq">What to do next</variable>
   <variable id="task_prereq">Before you begin</variable>
   <variable id="task_procedure">Procedure</variable>
   <variable id="task_procedure_unordered">Procedure</variable>
   <variable id="task_results">Results</variable>

Regards,
Radu

[Bas10R]

Hi Radu,

I'm publishing to WebHelp.
Thanks for this info, I'll have a go at it.

Kind regards,
Konrad

[Bas10R]

Hi Radu,

I was able to customise some of the strings as a test and get the appropriate results in my local WebHelp Responsive output.
In addition, I changed the text of some of the existing labels using https://www.oxygenxml.com/doc/versions/ ... nsive.html (used the DITA OT Integrator scenario though.)

Now, my project is stored in a Git repository and is supposed to act as a "template" for other authors in the company, who would simply fork the repo and proceed to use the project for their needs. How can I make sure that the changes I made (essentially creating a new DITA OT plugin, which as per instructions was done in the Oxygen installation directory) are included in that shared project?

For further context, the project has been created from the out-of-the-box Oxygen Startup Project, with DITA and DITA Map extension scripts, and a publishing template file.

Kind regards,
Konrad

[Radu]

Hi Konrad,
Maybe as an alternative you could see how those elements like "stepxmp" are published in the HTML content, then using CSS you could match those spans and add some ":before" static content to them. In this way maybe the CSS customization could be distributed more easily as part of a WebHelp publishing template.
Regards,
Radu

[Bas10R]

Hi Radu,

Unfortunately, in my company it's against some guidelines, see my initial post:

I'm aware such text can be added via CSS, but the resulting output isn't selectable and readable via screen readers (therefore against my company's localization and accessibility guidelines,) so I want to display these labels in the same way that labels such as "About this task" (<context>), "Results" (<result>), or "What to do next" (<postreq>) are displayed.

Would copying the DITA dir from the Oxygen installation directory to ${pd}/custom-settings/frameworks/dita, and then updating my project settings (Options > Preferences > DITA, with Project Options enabled) to use that folder as the custom DITA OT location be a valid approach?

Kind regards,
Konrad

[Bas10R]

Hi Radu,

Any ideas on how to effectively share this type of customisation across the team, as per my previous post?

Kind regards,
Konrad

[Radu]

Hi Konrad,
Sorry I forgot to reply to your next to last post.
So:

Would copying the DITA dir from the Oxygen installation directory to ${pd}/custom-settings/frameworks/dita, and then updating my project settings (Options > Preferences > DITA, with Project Options enabled) to use that folder as the custom DITA OT location be a valid approach?

The DITA OT publishing engine bundled with Oxygen is situated in the "OXYGEN_INSTALL_DIR/frameworks/dita/DITA-OT" folder. It can indeed be copied some place else (even to a framework extension folder) and then in the Oxygen Preferences->"DITA" page this custom DITA OT folder can be used instead of the one bundled with Oxygen.

Any ideas on how to effectively share this type of customisation across the team, as per my previous post?

Have you customized the WebHelp output before?
https://www.oxygenxml.com/doc/ug-editor ... aid-title5
A publishing template opt configuration file allows adding various extension points, some implemented with XSLT, like for example the publishing template for the Oxygen XML Blog:
https://github.com/oxygenxml/blog/blob/ ... mplate.opt
If you create a WebHelp publishing template folder it can be kept outside of the DITA OT installation folder and using in the ".opt" file an extension point like this:

Code: Select all

<extension 
              id="com.oxygenxml.webhelp.xsl.dita2webhelp"
              file="xsl/customDita2webhelp.xsl"/>

allows you to specify an XSLT stylesheet which could override specific XSLT templates from the base "org.dita.html5" plugin.
After you have a publishing template you can edit the DITA to WebHelp Oxygen transformation scenario you are using and use it in the "Templates" tab.

Regards,
Radu

[Bas10R]

Thank you, Radu, creating such an extension point and referencing it in my .opt file in the project should cover this scenario.