RE: Differences between specs and DTDs

["Kristen Eberlein" <keberlein@sdl.com>]

Hi, Jang.

The DITA TC discussed your e-mail this morning. We also examined that DITA
1.2 spec and came to the following conclusions:

* The DTDs and the architectural spec topics are consistent.

* Some of the language reference topics are internally inconsistent. For
example, section 3.2.2.2 taskbody has conflicting information in the Contains
table and a note that reads "One model, referred to as the general task,
allows two additional elements inside the task body (<section> and
<steps-informal>); it also allows multiple instances and orders for each
element within <taskbody>." In contrast, the Contains table indicates the
correct content model and matches the DTD.

The wording is poor. It perhaps should read as follows:

Note: Beginning with DITA 1.2, the DTD and Schema packages distributed by
OASIS  contain two task models. The general task model allows two additional
elements inside the task body (<section> and <steps-informal>); it also
allows multiple instances and varying order for the <preq>, <context>, and
<section> elements. The strict task model maintains the order and cardinality
of the DITA 1.0 and 1.1 <taskbody> content model. This strict task is
implemented in the DTD and Schema with a constraint module.

We are grateful to you for bringing this matter to our attention and will
make sure that the next version of the DITA 1.2 spec correctly addresses this
issue.

Best regards,
Kris
Kristen James Eberlein l DITA Architect and Technical Specialist l SDL
Structured Content Technologies Division l (t) + 1 (919) 682-2290 l
keberlein@sdl.com

Please consider the environment before printing this e-mail



-----Original Message-----
From: jang@jang.nl [mailto:jang@jang.nl] 
Sent: Monday, June 06, 2011 6:50 AM
To: dita-adoption@lists.oasis-open.org
Subject: [dita-adoption] Differences between specs and DTDs

Hello everyone,

After a long period of minding other business and riding a motorbike across
the USA, I am back on the DITA adoption track and writing feature articles
for Machinery-related stuff. I stumble across inconsistencies between the
DTDs and the language specs document released in December. Not sure if this
has been discussed before - in that case a pointer to that discussion would
be appreciated.

This is about the general task introduced in DITA 1.2. In the specs for
<task> and <taskbody> it is stated that the new general task model allows
multiple instances and orders for each element within taskbody. This is
reinforced by a note in the <steps> element description, where it is stated
that multiple <steps> elements can be included in the same task. In the DTDs
however, this is not implemented:

<!ENTITY % taskbody.content
                       "(((%prereq;) | 
                          (%context;) |
                          (%section;))*,
                         ((%steps; | 
                           %steps-unordered; |
                           %steps-informal;))?, 
                         (%result;)?, 
                         (%example;)*, 
                         (%postreq;)*)"

There is an extra set of brackets around the <steps>, <steps-unordered>,
<steps-informal> set of elements  which do not seem to have any meaning. If
the DTDs are leading, the specs are wrong in multiple locations. If the specs
are leading, the DTD should show an asterisk or a plus (depending on whether
a taskbody without any steps should be allowed or not).

I am including a short description of the relaxation in the task model in my
feature article on the machinery task, as it is quite essential, so I would
like to clear this point up.

Greetings from Amsterdam

Jang