"example should only contain one title element"

[Lemesany]

I'm on Author 20.1, and a warning is appearing in some of my tasks: "example should only contain one title element". I don't recall this in previous version of Oxygen.

Sample code of an example in a task:

Code: Select all

 <example><title>example 1</title>

            <p>content</p>

            <title>example 2</title>

            <p>content</p>

            <title>example 3</title>

            <p>content</p>

            </example>

In concepts, we can split the examples. Tasks don't allow for this.
My question is: Is this an OASIS standard?

This page states that you can have any number of titles: http://docs.oasis-open.org/dita/v1.2/os ... ml#example

This page doesn't mention it: https://www.oxygenxml.com/dita/1.3/spec ... ample.html

This page has a note about using only one title element, but it's for sections: https://www.oxygenxml.com/dita/1.3/spec ... ction.html

Can you please help clarify whether multiple titles in an example is okay?

BTW, I also get "Title must be the first element in a section" in references>sections, but I think your note in my last link clarifies that...

[Radu]

Hi Beth,

Indeed the DITA 1.3 specification states quite clearly that a DITA <section> should have only one title and that it should come first.
But for DITA <example> it does not have the same note in the specification.
Honestly I do not know what their intention with <example> is so I just asked this question on the dita-comments OASIS list:

https://lists.oasis-open.org/archives/d ... 00000.html

You can try to register on the list if you want, they usually try to answer questions there but it takes some time.
In the meantime, that particular warning you receive when having an example with multiple titles is given by this Schematron rule:

OXYGEN_INSTALL_DIR\frameworks\dita\resources\dita-1.2-for-xslt2-mandatory.sch

which has inside a pattern with ID multiple_example_titles that could be commented out.
You can also customize the Schematron validation in the DITA framework and share the customization with other members of the team:
http://blog.oxygenxml.com/2017/02/shari ... rules.html

This warning has been around for a long time so I'm not sure why you did not notice it in the past.
I will also add an issue on our side to reconsider if we should issue the warning or not, depending on what the DITA TC will say about this.

Regards,
Radu

[Radu]

Hi Beth,

Finally got an answer from the DITA TC on this specification-related question:
https://lists.oasis-open.org/archives/d ... 00001.html
So they recommend you to create a "General Task" instead of a basic "Task". Something like:

Code: Select all

<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA General Task//EN" "generalTask.dtd">
<task id="task_hxp_cwm_rhb">
    <title></title>
    <shortdesc></shortdesc>
    <taskbody>
        <context>
            <p></p>
        </context>
        <example/>
        <example/>
    </taskbody>
</task>

Oxygen has new file templates to create both.

Regards,
Radu