<example> in <section>

[AlastairDent]

I have a need for <section>s in general tasks. Inevitably I then also need <example> tags.

However Oxygen validation objects saying:

E [Xerces] Unexpected element "example". The content of the parent element type must match "(dl|parml|div|equation-block|fig|imagemap|syntaxdiagram|equation-figure|image|lines|lq|note|hazardstatement|object|ol|p|pre|codeblock|msgblock|screen|simpletable|sl|table|ul|boolean|cite|keyword|markupname|apiname|option|parmname|cmdname|msgnum|varname|wintitle|numcharref|parameterentity|textentity|xmlatt|xmlelement|xmlnsname|xmlpi|ph|b|i|line-through|overline|sup|sub|tt|u|codeph|synph|filepath|msgph|systemoutput|userinput|menucascade|uicontrol|equation-inline|q|term|abbreviated-form|text|tm|xref|state|data|sort-as|data-about|foreign|svg-container|mathml|unknown|sectiondiv|title|draft-comment|fn|indextermref|indexterm|required-cleanup)".

In that validation it says that the parent element can be 'p'.

So I put <element> inside <p> tags. Oxygen validation objected but this time saying:
E [Xerces] Unexpected element "example". The content of the parent element type must match "(dl|parml|div|equation-block|fig|imagemap|syntaxdiagram|equation-figure|image|lines|lq|note|hazardstatement|object|ol|pre|codeblock|msgblock|screen|simpletable|sl|table|ul|boolean|cite|keyword|markupname|apiname|option|parmname|cmdname|msgnum|varname|wintitle|numcharref|parameterentity|textentity|xmlatt|xmlelement|xmlnsname|xmlpi|ph|b|i|line-through|overline|sup|sub|tt|u|codeph|synph|filepath|msgph|systemoutput|userinput|menucascade|uicontrol|equation-inline|q|term|abbreviated-form|text|tm|xref|state|data|sort-as|data-about|foreign|svg-container|mathml|unknown|draft-comment|fn|indextermref|indexterm|required-cleanup)".

I can place an <example> tag after a <section>, but not if that <section> is followed by another <section>.

This does not seem right!

[Radu]

Hi,

Could you paste a codeblock example of how your DITA topic/task looks like?
Although I'm afraid we cannot do much, Oxygen uses the DTDs provided by the OASIS DITA specs to validate the XML document.

Regards,
Radu

[AlastairDent]

I understand that you are validating against standard DTD, but in this case the logic seems wrong.

This is accepted:

Code: Select all

<section>

            <title>some title</title>

            <ol id="ol_dvh_sqb_3w">

                <li>a step.</li>

                <li>another step</li>

            </ol>

        </section>

        <example>

            <p>For example:</p>

            <codeblock>Some lines of code</codeblock>

        </example>

This is not:

Code: Select all

<section>

            <title>some title</title>

            <ol id="ol_dvh_sqb_3w">

                <li>a step.</li>

                <li>another step</li>

            </ol>

	<example>

            <p>For example:</p>

            <codeblock>Some lines of code</codeblock>

        </example>

        </section>

Nor is this:

Code: Select all

<section>

            <title>some title</title>

            <ol id="ol_dvh_sqb_3w">

                <li>a step.</li>

                <li>another step</li>

            </ol>

        </section>

        <example>

            <p>For example:</p>

            <codeblock>Some lines of code</codeblock>

        </example>

	

<section><title>another title</title>

            <p>somthing</p>

        </section>

[Radu]

Hi Alastair,

Please post an entire DITA topic sample (along with DOCTYPE declaration).
In the first post you mentioned "general task". A general task is a topic specialization and I need to know in what location in the general task you are including that sample content you posted.

Regards,
Radu

[AlastairDent]

Not accepted

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA General Task//EN" "generalTask.dtd">

<task id="Sample-generalTask">

    <title>Sample General Task</title>

    <shortdesc>Short Description</shortdesc>

    <taskbody>

        <context><p>This isa normal paragraph.</p></context>

        <prereq> This is tagged with <prereq>. </prereq>

	<section>

            <title>some title</title>

            <ol id="ol_dvh_sqb_3w">

                <li>a step.</li>

                <li>another step</li>

            </ol>

	<example>

            <p>For example:</p>

            <codeblock>Some lines of code</codeblock>

        </example>

        </section>

    </taskbody>

</task>

Or

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA General Task//EN" "generalTask.dtd">

<task id="Sample-generalTask">

    <title>Sample General Task</title>

    <shortdesc>Short Description</shortdesc>

    <taskbody>

        <context><p>This isa normal paragraph.</p></context>

        <prereq> This is tagged with <prereq>. </prereq>

	<section>

            <title>some title</title>

            <ol id="ol_dvh_sqb_3w">

                <li>a step.</li>

                <li>another step</li>

            </ol>

	

        </section>

        <example>

            <p>For example:</p>

            <codeblock>Some lines of code</codeblock>

        </example>

        <section>

        <p>anything</p>

        </section>

    </taskbody>

</task>

[Radu]

Hi Alastair,

Thanks for the samples.
So:

1) You cannot insert an example inside a section. This is stated also in the DITA 1.2 specs which describes the content model (list of allowed children) for section:

http://docs.oasis-open.org/dita/v1.2/os ... ml#section

2) As a workaround in a generic DITA topic you can add an <example> after a <section>.
Indeed this workaround does not work for the General Task specialization.
Here is the content model of the General Task taskbody element defined in the specs:

https://www.oxygenxml.com/dita/1.3/spec ... __taskbody

Code: Select all

(<prereq> | <context> | <section>)*, (<steps> | <steps-unordered> | <steps-informal>)?, <result>?, <tasktroubleshooting>?, <example>*, <postreq>*

meaning that after you insert an <example> (which is optional) no other element may follow it except the <postreq> element.
That's how the DTD is written and what the specs states. There is a special mailing list to which you can subscribe to ask questions to the OASIS members who work on the DITA standard:

https://www.oasis-open.org/committees/c ... bbrev=dita

Probably in your case the General Task is too restrictive and you can rewrite it as a regular topic.

Regards,
Radu