[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: Updated summary: task vs. general task, constraints, conref, and other related issues
During last week’s DITA TC
meeting we resolved the first two open items on the list of open questions related
to task vs. general task, constraints, conref and other related issues. And we almost resolved the 3rd
and 4th items as well, but at the last minute Michael and Eliot
realized that implementing the proposals for these two items would mean that we
wouldn’t be following some aspects of our design guidelines. Time ran out at
that point and so we’ll be coming back to these issues during our next meeting. The two remaining items are: 3. The names we have for task.dtd,
generalTask.dtd, task.mod, task.ent, strictTaskbodyConstraint.mod and the
associated XSDs, Public IDs, and URIs seem confusing. Would new names for
some of the these items help? task.dtd might become strictTask.dtd,
task.mod --> genTask.mod, task.ent --> gentask.ent. For compatibility
with DITA 1.1 and 1.0 we’d probably need to use the same sort of trick we used
with glossary and glossentry, so the old names would continue to work. Proposal: To make some name changes so
that it is clearer what each file includes or does. 4. Any user specializations based on
task.mod from DITA 1.0 or 1.1 will switch from being strict to general task
based specialization when people move to DITA 1.2 unless explicit action is
taken to add the strict task constraint to the specialization. This is
pretty much want happened to us with ditabase.dtd. We need to add something to
the DITA 1.2 specification warning people about this possibility. Or, if we
rename some items as suggested in the previous item, we might be able to avoid
this problem by having a genTask.mod, a strictTask.mod, and a task.mod where
task.mod would include the strict task constraint. Proposal: To make a change along the lines of
the later suggestion, so that previously existing specializations based on
task.mod include the strict task constraint and so do not implicitly change
when used with DITA 1.2. Don was working to combine the
two items into a single item as follows: “changing filenames for compatibility
and clarity”. But at least for item #4 there is a
little more to it than just changing filenames. Since it seems likely that there
is going to be substantial opposition to these two items, after last week’s
call I tried to figure out if it was worth it to continue to push for these two
items. My conclusion is that the changes are worth making even if we don’t
follow all of our own design guidelines. My thinking is that the changes will avoid
a change in behavior for existing specializations that use task.mod (from
strict to general task), as well as reduce the chance for confusion going
forward, that we’ve already seen confusion caused by this on the part of the
DITA TC, and we really need to try and make things easier and more
understandable for folks with less in depth knowledge of DITA, DTDs, and XSDs.
And we can mitigate the issues of not strictly following the design guidelines
by providing and using good examples as alternates to the files that do follow
the guidelines. In the files and in the Architecture Spec. we can include an explanation
of what we are doing, why we are doing it, and stating that the files that do
not follow the guidelines should not be used as examples for the future development. So my current suggestion is: ·
That we not combine
items 3 and 4. ·
That we split item 3
into two parts: 3a)
changing names that do follow the design guidelines (task.dtd becomes
strictTask.dtd, with task.dtd kept for compatibility, but deprecated); and 3b)
changing names in ways that do not follow the design guidelines (task.mod
becomes generalTask.mod, with task.mod kept for compatibility, but deprecated).
·
And that the TC
consider items 3a, 3b, and 4 separately. The objection to item 3b is that
the name of the file (generalTask.mod won’t match the name of the information
type or top tag, task). The objection to item 4 is that
adding the Strict Task Constraint to task.mod violates the principle that
integration of types, domains, and constraints is done in document type shells
and not in modules. -Jeff From: Ogden, Jeff Here is
another updated summary of the issues related to task vs. general task,
constraints, conref, and other related matters. The
summary is also available as a Wiki
page under the “Working Documents, DITA 1.2” section of the DITA TC Wiki page. I’ve
placed the issues into two groups. The first group includes questions
that still need to be resolved. The second group includes issues that I
believe have been resolved or deferred. If I’ve
left anything out or there are other questions that need to be discussed and
decided, please add them to the list. Robert
wrote an FAQ about constraints that everyone who is interested in this topic
should read:
http://wiki.oasis-open.org/dita/ConstraintsFaq
Open
questions: 5. There was a preliminary proposal to
allow “weak” constraints to be declared. Michael formalized this as a
proposal to allow both “strong” and “weak” constraints validation with
“weak” being the default. No one raised technical complaints about the original
proposal. There has been support for including the proposal as part of DITA 1.2
expressed by several people. There have been reservations about considering the
proposal this late in the DITA 1.2 cycle. If the strong/weak constraints
proposal goes forward, my assumption is that we will use the default of “weak”
in task.dtd and in ditabase.dtd. The proposal requires changes to the
written specification, but no changes to the DTDs or XSDs. It may require
changes to some implementations, but perhaps not difficult or extensive
changes. Proposal: Accept Michael’s proposal for DITA
1.2 with “weak” conref validation of constraints as the default and “strong”
conref validation of constraints something that may be implemented, but is not
required.. 6. There is an open question about the
need to include a second ditabase doctype shell that would include general task
rather than strict task. The TC seemed to be leaning toward not including
a second ditabase doctype shell, but I don’t think there is a consensus about
that and a final decision remains to be made. If a decision is made to
include a second ditabase, we would need to pick a location for the additional
doctype shell, filenames, a Public ID, and a URI, and the DTDs, XSDs, and the
DITA specification would all need to be updated. Proposal: Include only a single ditabase
document type in DITA 1.2. 7. The names we have for task.dtd,
generalTask.dtd, task.mod, task.ent, strictTaskbodyConstraint.mod and the
associated XSDs, Public IDs, and URIs seem confusing. Would new names for
some of the these items help? task.dtd might become strictTask.dtd,
task.mod --> genTask.mod, task.ent --> gentask.ent. For compatibility
with DITA 1.1 and 1.0 we’d probably need to use the same sort of trick we used
with glossary and glossentry, so the old names would continue to work. Proposal: To make some name changes so
that it is clearer what each file includes or does. 8. Any user specializations based on
task.mod from DITA 1.0 or 1.1 will switch from being strict to general task
based specialization when people move to DITA 1.2 unless explicit action is
taken to add the strict task constraint to the specialization. This is
pretty much want happened to use with ditabase.dtd. We need to add something to
the DITA 1.2 specification warning people about this possibility. Or, if we
rename some items as suggested in the previous item, we might be able to avoid
this problem by having a genTask.mod, a strictTask.mod, and a task.mod where
task.mod would include the strict task constraint. Proposal: To make a change along the lines of
the later suggestion, so that previously existing specializations based on
task.mod include the strict task constraint and so do not implicitly change
when used with DITA 1.2. Issues
that I believe have been resolved or which have been deferred to DITA 1.3 or
2.0: 9. The TC has decided that strict task
rather than general task should be included in the ditabase doctype shell that
is included as part of Technical Content. DTDs, XSDs, and the DITA 1.2
specification will all need to be updated. 10. Questions were raised about the
constraints mechanism in general and if it was appropriate to use it to
implement the new versions of task that are part of DITA 1.2. At the TC
meeting two weeks ago Joann made a proposal to abandon the current approach of
using constraints to implement general and strict task in DITA 1.2. As an
alternative she suggested two peer task specializations both based on topic.
Others suggested that implementing strict task as a specialization of general
task without using constraints as another approach. After a good deal of
discussion, it was decided that we should stick with the current approach of
using constraints to implement strict task based upon general task. 11. It has been stated that within a
single organization or within a single authoring group, that in general only
one version of an information type SHOULD be used within a group and that we
should explain why that is the case and recommend that approach somewhere in
the DITA 1.2 specification as well as in a best practices document that might
be written by the DITA Adoption TC. There were a number of questions
about exactly what should be said and where it should be said, but there was
agreement that something should be said in both the DITA specification and in a
best practices document. 12. There was a question about the wisdom
of including both task.dtd (strict task) and generalTask.dtd in the DITA 1.2.
Given the previous item we will include both with appropriate warnings and
recommendations in the specification and a best practice. 13. There was a lot of discussion about
what is and isn’t or what should and shouldn’t be valid when using conref.
There was one question about doing conref validation based on content models in
DTDs or XSDs rather than information in the domains attribute value.
Several people pointed out why DITA doesn’t use the actual content models in
the DTDs or XSDs for conref validation and instead uses values from the domains
attribute. 14. Many of the issues we’ve been
discussing seem to arise from shortcomings of ditabases and shortcomings of
DTDs --that a ditabase can only contain a single use (constrained or unconstrained)
of a particular info type. We should look for ways to remove or relax
these restrictions in DITA 1.3 or 2.0. 15. Eliot added some questions about topic
nesting, conref validation, and the domains attribute to the list of things to
consider for DITA 1.3. |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]