RE: [dita] RE: Differences between specs and DTDs

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

Hi, Jang.

I suggest that we bring this up for discussion again at a DITA TC meeting at
which Robert Anderson is present. He might well be aware of some of the back
history. Then it might well be properly handled as an item for the Machine
Industry SC.

Has that SC been meeting since you and Jonatan Lundin took over as co-chairs?


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 F.M. Graat [mailto:jang@jang.nl] 
Sent: Tuesday, June 07, 2011 1:35 PM
To: Kristen Eberlein
Subject: Re: [dita] RE: Differences between specs and DTDs

Hello again Kris,

Thanks for the info. But even with the proposed interpretation of the  
ambiguous taskbody description there remains a problem, as the wording  
in the description of the steps and steps-unordered elements is as  
clear as can be:

Note: Beginning with DITA 1.2, the general task model allows multiple  
<steps> and <steps-unordered>
elements. However, the default task model in the OASIS distribution  
(known as strict task) continues to
allow only one <steps> or one <steps-unordered> element.

This suggests that the general task was intended to allow multiple  
steps and steps-unordered elements. It may be that the intention to  
include multiple steps and/or steps-unordered elements within a  
taskbody was more or less forgotten in further discussions and was  
thereby lost in the tables, the architectural specs and the DTDs. It  
might be useful to check the minutes of the meetings where the general  
task was discussed.

Not that anything can be done about it in 1.2, as the specs are  
ambiguous and the majority of occurrences indicate only one steps or  
steps-unordered element, but it might be an idea to revisit the  
discussion in the preparations of DITA 1.3. I can see clear business  
cases for the further relaxation of the general task on this point,  
where two alternative procedures for the same task can be given,  
depending on the context that is given in the header of the task. As  
machine industry task may contain a lengthy section with safety  
notices, supplies, equipment etc. plus possibly images and  
corresponding legend, it would be useful to allow inclusion of more  
than one set of steps in the same topic. It would not be feasible to  
organize them into 2 steps with all commands listed in substeps, as  
this takes away much of the advantages of having a machine industry  
task in the first place.

Is this something we can discuss in the Machine Industry SC and then  
propose for DITA 1.3 or should all discussion on the general task be  
done elsewhere ?

Kind regards

JANG Communication
Coaching - Copywriting - Consulting
Amsterdam - Netherlands
Tel.  +31 20 755 8466
Cell +31 6 5478 1632
http://www.jang.nl

On 7 jun 2011, at 18:57, Kristen Eberlein wrote:

> 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