Thanks, Su-Laine,
You’ve provided a very good analysis and
suggested rewordings to clarify the situation. I still have a problem, of
course, with the assumption that constraints are “easy” to implement and with
the confusion about providing both task models, carefully named, in the “out of
the box” editor solutions.
JoAnn
JoAnn Hackos PhD
President
Comtech Services, Inc.
joann.hackos@comtech-serv.com
Skype joannhackos
From: Su-Laine Yeo
[mailto:su-laine.yeo@justsystems.com]
Sent: Thursday, September 10, 2009
8:20 PM
To: Erik Hennum; JoAnn Hackos
Cc: dita@lists.oasis-open.org; Harold Trent
Subject: RE: [dita] constraints
support? (Was: Problems with the task model)
Here’s my take on
various issues below:
1) Will applications
support the constraints feature?
For XMetaL we are
considering it, but the feature is actually very difficult to fully implement
in a robust way. I recommend that we deliver DITA 1.2 DTDs, XSDs, and
documentation in such a way that authors can easily use both task models,
regardless of whether their tools have awareness of the DITA constraints
feature.
2) “That means that
companies that are using and want the strict task model are stuck. It’s not
being made available. Are we going to see that with all the editor vendors
because they don’t understand that there are now two task types?”
No. It is easy for a
product to support both the restrictive task DTD and the generalTask DTD, and
as Eliot pointed out you can probably configure most authoring tools to use
whatever DTD you want. But we should change the documentation because I can see
that the current draft of the langref doesn’t encourage vendors to support the
more restrictive task type in out-of-the-box products, *except* via the
constraints model.
3) “I don’t see
anything in the lang ref, the dtd or the Arbortext 5.4 implementation any
provision for additional sets of steps. Where is this supposed to happen?”
The langref is
confusing because when it says a task “may define more than one set of steps”,
people might expect this to mean that a task would allow more than one
<steps> element. I think what it’s trying to say is that you can use the
<steps-informal> element and put multiple <ol> elements
inside <steps-informal>.
Here are some
suggested rewordings for the description of <task> in the langref:
- “In the document types provided by OASIS with DITA 1.0 and
1.1, the task only allowed a single set of either <steps> or
<steps-unordered> elements, and a set could contain only <step>
elements. In DITA 1.2 there are two task models: a restricive task model which
is identical to DITA 1.1, and a looser “general” task model. The chief
difference between the two is that the looser model can contain a
<steps-informal> element which can contain a wide variety of elements,
including one or more <ol> elements. The restrictive task model is
delivered in two ways: as a set of constraints on the general task document
type, and as its own document type. If there is a difference between these two
methods of delivery, the constraints method is considered the normative one.
Task topics within <ditabase> and <learningContent> use the looser
model.”
- In the Doctype column of the table, change “ditabase,
learningContent” to “ditabase, learningContent, generalTask”.
- Change:
“The <taskbody> element is the main body-level element
inside a task topic. A task body is designed to contain information specific to
completing a task, such as prerequisites, contextual information, and steps.
With DITA 1.2, the content model of taskbody is looser to accommodate
additional task structures. OASIS provides a DITA constraint that mimics the
previous tight content model so that users continue to have easy access to the
strict model.”
to this:
“The <taskbody> element is the main body-level element
inside task topic. A task body is designed to contain information specific to
completing a task, such as prerequisites, contextual information, and
instructions.”
Regards,
Su-Laine
Su-Laine Yeo
Interaction Design Specialist
JustSystems
Canada, Inc.
Office: 778-327-6356
syeo@justsystems.com
www.justsystems.com
From: Erik Hennum
[mailto:ehennum@us.ibm.com]
Sent: Thursday, September 10, 2009
4:40 PM
To: JoAnn
Hackos
Cc: dita@lists.oasis-open.org; Harold Trent
Subject: [dita] constraints
support? (Was: Problems with the task model)
Hi, JoAnn:
Separating the constraints and task model issues -- although the name
"constraints" sounds like something that requires special tooling, in
fact constraints mostly affect the DITA vocabulary designer. Constraints refine
the pattern for implementing a DTD or XML Schema.
Constraints don't add to the following core editor implementation tasks:
** Document validation. Generic DTD or XML Schema support is all that's needed
to validate documents with constrained DITA vocabularies.
** Rendering and editing behaviors. Basic specialization support (sensitivity
to the base vocabulary and matching vocabulary names in the class attribute) is
all that's needed for rendering and editing constrained DITA vocabularies.
An editor tool only needs awareness of constraints during conref checks.
Specialization already imposes some requirements for verifying generalizability
by inspecting the architectural attributes, but constraints adds to those
requirements.
In short, for an editor tool, constraints have a low cost for an enhancement
that can improve the usability of structured documents.
A vocabulary design tool would be a different story -- I can readily see how
constraints could pose a significant challenge for tooling in that area.
If I'm naive about the implementation challenges, maybe an editor implementer could
clarify.
Erik Hennum
ehennum @ us.ibm.com
"JoAnn
Hackos" ---09/10/2009 02:56:25 PM---I've spent the
entire day trying to figure out what has happened to the task model since I'm
trying
From:
|
"JoAnn Hackos"
<joann.hackos@comtech-serv.com>
|
To:
|
<dita@lists.oasis-open.org>
|
Cc:
|
"Harold Trent"
<harold.trent@comtech-serv.com>
|
Date:
|
09/10/2009 02:56 PM
|
Subject:
|
[dita] Problems
with the task model
|
I’ve spent the
entire day trying to figure out what has happened to the task model since I’m
trying to write the Technical Content section of the Arch Spec.
If you look at the 1.2 lang
spec, <task>, you’ll find this claim
“In the document types
provided by OASIS with DITA 1.0 and 1.1, the task only allowed a single set of
steps. In DITA 1.2 this restriction is relaxed so that a task may define more
than one set of steps. However, OASIS will continue to distribute a sample
document type that only allows a single set (using the new constraints
mechanism available with DITA 1.2), for use by those that prefer the more
restrictive model.”
The original strict task model
is in OT 1.5. However, in PTC’s Arbortext 5.4, there is only the “generic”
loose task model.
Also, I understand that
Arbortext will not support the constraint mechanism with this release. Doesn’t
seem to be in future plans either.
That means that companies that
are using and want the strict task model are stuck. It’s not being made
available. Are we going to see that with all the editor vendors because they
don’t understand that there are now two task types?
Next,
I looked at the 1.2 lang spec,
<taskbody> .
It shows the generic task
model (loose) as contained in ditabase and the standard original better task
model in “task”. Makes no sense of course
Then, to quote
“The <taskbody> element
is the main body-level element inside a task topic. A task body is designed to
contain information specific to completing a task, such as prerequisites,
contextual information, and steps. With DITA 1.2, the content model of taskbody
is looser to accommodate additional task structures. OASIS provides a DITA
constraint that mimics the previous tight content model so that users continue
to have easy access to the strict model.”
Another quote:
In the document types provided
by OASIS with DITA 1.0 and 1.1, the task only allowed a single set of steps. In
DITA 1.2 this restriction is relaxed so that a task may define more than one
set of steps. However, OASIS will continue to distribute a sample document type
that only allows a single set (using the new constraints mechanism available
with DITA 1.2), for use by those that prefer the more restrictive model.
I don’t see anything in the
lang ref, the dtd or the Arbortext 5.4 implementation any provision for
additional sets of steps. Where is this supposed to happen?
How do we correct these
issues?
JoAnn
JoAnn Hackos PhD
President
Comtech
Services, Inc.
joann.hackos@comtech-serv.com
Skype
joannhackos
[attachment
"DITA task.png" deleted by Erik Hennum/Oakland/IBM] ---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave
the OASIS TC that
generates this mail. Follow this link to all
your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php