OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [dita] regrets, and opposition to including item 12051 as aneasy 1.2 fix

That's it in a nutshell Michael:
The logic behind putting architectural attributes on the topic element rather than the <dita> element is that topics are the focus of the architecture.... If we put the architectural attributes on the <dita> element, we tie the topics inside it to that container, which undermines the portability of the topics.
And that's why I still think we can't really include this item on the "easy to fix" list - and have much hope of getting 1.2 out the door as quickly as Paul would like.


Michael Priestley wrote:

How is this problem any different from incorporating different domains into the same structural type?

Maybe what we need is for the topic-nesting in an architectural attribute somehow, in the way we do for domains - that would be consistent with the way we deal with the problem there, although it would definitely need some design work. It might be possible to do as part of the general work on expressing constraints - effectively, say that topic-nesting is a particular kind of constraint, and should be reflected as such in an architectural attribute.

The alternative of defining a new root element for each new document type shell seems like a departure from the direction set with domains, and won't help applications that have to deal with the domain situation (eg multiple <task> topic types with different domains integrated and thus different content models). In other words, the root element is never a good indicator of doctype or content model in DITA, whereas the architectural attributes are designed to be, so maybe we need an architectural attribute solution (not on the <dita> element itself, but on the <topic> element, where the other architectural attributes sit).

The logic behind putting architectural attributes on the topic element rather than the <dita> element is that topics are the focus of the architecture: we can't guarantee where a topic will be over time (file system, database, inside a ditabase document...) but we can guarantee what will be allowed in the topic wherever it resides (content model, domains, etc.). If we put the architectural attributes on the <dita> element, we tie the topics inside it to that container, which undermines the portability of the topics.

Michael Priestley
IBM DITA Architect and Classification Schema PDT Lead

"Grosso, Paul" <pgrosso@ptc.com>

04/16/2007 01:09 PM

Michael Priestley/Toronto/IBM@IBMCA
RE: [dita] regrets, and opposition to including item 12051 as an easy 1.2 fix

A ditabase is designed to allow different content models at
different times.  But to allow different content models, you
have to change the DTD or Schema used for a ditabase.  You can
certainly do that without specialization and without changing
the name of the root tag.  But, if you do it that way, how can
anyone know what it is that has been done and which of the many
possible ditabase content models is being used?  I guess they
could look through all of the topics included in the ditabase
and make sure that they have a ditabase DTD that includes them
all.  Seems like a pain.  

The alternative that we're suggesting is just that people should
give different names to their new doctypes and use a new name
for the root tag.  And the dita specialization mechanism seems
like a good way to do that and to let people know what you've
done.  Perhaps it isn't a true specialization since what you
should be doing at this level is just adding and removing topic
types from the content model.

If there is a good reason for not allowing specializations of
the dita element, how about adding class to <dita> without adding
the ability to specialize <dita>.  In this case the class attribute
would have a fixed value that wouldn't change, but it would identify
the top tag as a DITA topic type.


> -----Original Message-----
> From: Michael Priestley [mailto:mpriestl@ca.ibm.com]
> Sent: Thursday, 2007 April 12 17:38
> To: Grosso, Paul
> Cc: dita@lists.oasis-open.org
> Subject: RE: [dita] regrets, and opposition to including item
> 12051 as an easy 1.2 fix
> "Grosso, Paul" <pgrosso@ptc.com> wrote on 04/06/2007 10:21:09 AM:
> > I could be missing some details, and I expect someone
> > like Michael to correct me if I'm wrong, but let me
> > explain things the way I understand them.
> I'm late to my cue, but I'll add some thoughts.
> > More accurately, it currently allows you to put topic, task,
> > concept, and reference together in a single document.  It
> > does not allow you to put other topic-level things that you
> > may have created as specializations of topic.  That's the
> > problem.
> The <dita> element was originally intended to be a bucket for
> holding any kind of topic type - so it could be used in any
> shell document type to assemble any number of different topic
> types. I think we're running into one of those legacy
> problems with the language spec being adapted from a language
> reference, so content that was once merely descriptive (this
> is what it does for the 1.0 doctypes) has become prescriptive
> (this is what it must do for any doctype).
> There's no processing associated with the element explicitly
> because it was a bucket with unknown content.
> >
> > When we create a new generalized topic (or whatever we are
> > calling it) in DITA 1.2, it will not be able to be put into
> > a ditabase document (unless we change the dita element's
> > content model specially for the element we add).
> >
> > The point is that any user that creates a new specialization
> > of topic isn't going to be able to put those new elements
> > into a ditabase document unless they can create a specialization
> > of the dita element.
> The dita element is actually declared in the shell doctype,
> rather than in a module, so that its content model can be
> controlled/declared in the shell, rather than in a module. In
> other words, its content model is expected to be different in
> different doctypes, without using specialization. Since there
> is no processing associated with the dita element, there is
> nothing to inherit from specialization, and nothing to break
> by changing its content model for new authoring contexts.
> That said, nesting of topic types in general, as well as
> containment of topic types under <dita>, is controllable
> without specialization generally. The info-types entity, and
> its type-specific equivalents, can be redefined in shell
> document types without requiring specialization: I can create
> my own doctype that says concepts nest tasks, for example,
> purely by manipulating the shell and without declaring new elements.
> So in this respect, the behavior of the <dita> element (you
> can add new topic types to its content model without
> requiring specialization) is already consistent with the
> control of topic type containment elsewhere in the model.
> > > As such, it needs no class attribute - since the sole
> > > function of that attribute is to preserve output implications
> > > across specializations.
> >
> > I'm not sure what "preserve output implications across
> > specializations" means, but the function of the ditabase
> > document type (and hence the dita element) is to allow a
> > user to collect various topic-level elements into one
> > document.
> >
> > And they can't include their own topic-specializations
> > in a ditabase document as things stand.
> >
> > >
> > > To add a class attribute to the dita element and make it
> > > available for specialization is a major architectural change
> > > that requires careful thought, not a simple easy fix.
> >
> > I don't see how allowing specialization on the one DITA element
> > that currently does not allow it as a major architectural change.
> >
> > paul
> I think that the current documentation for the dita element
> is unclear - I'd like to correct it for 1.1 to make its
> purpose as a general-purpose aggregator more explicit. The
> architectural spec would need an explicit mention of the
> <dita> element in the design pattern section, effectively
> saying that you just copy it over into the doctype shell. And
> we could add a clarifying paragraph to the language spec as
> well. But given that specialization is not necessary to
> change the content model, I'm not sure that we'd want to make
> it specializable - it would imply that it should be
> processable, which in turn would be a major change, so I
> share Dana's concern in that regard.
> Michael

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]