RE: [dita] Proposal: Update foreign topic to include processing info forgeneralization/specialization use case

[Robert D Anderson <robander@us.ibm.com>]

Hi Yas,

Generalization is already described in the specification:
http://docs.oasis-open.org/dita/v1.0/archspec/generalize.html

Generalization is in there in the first place because the specification has
to tell people how to back out of a given specialization (for whatever
purpose). One of the premises of specialization is that you can back out to
a more general level and share content, so I think we have to describe what
that means. It helps to ensure that any DITA processor can understand both
specialized and generalized content.

The only reason that foreign content needs to be called out in the
generalization topic is that the elements inside are not actual DITA
elements, so the ordinary generalization rules cannot be applied. So, we
have to say what to do with it, or we have a hole in that topic. This
doesn't really seem like processing behavior to me - it explains how
foreign content appears in its specialized and generalized form. How it
gets from one to the other, and how processes display/edit/process the
content, is left up to those processors.

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit
(507) 253-8787, T/L 553-8787

"Yas Etessam" <yas.etessam@xmetal.com> wrote on 10/23/2006 02:01:01 PM:

> Robert and Paul,
>
> I would support this proposal.  If we go with this approach, can we
> avoid saying that all processors should hide foreign content as an
> external object in the specification?  I agree with Paul that this level
> of detail about processing behaviour does not need to be codified in the
> spec.
>
> One suggestion is that we define "generalization" as a process that
> produces standard DITA topics from specialized topics.   This could
> allow different implementations of processing when it comes to deciding
> what should be done with foreign vocabularies and defines a measurable
> benchmark.
>
> Best regards,
>
> Yas Etessam
>
>
> -----Original Message-----
> From: Robert D Anderson [mailto:robander@us.ibm.com]
> Sent: Monday, October 23, 2006 8:36 AM
> To: dita@lists.oasis-open.org
> Subject: RE: [dita] Proposal: Update foreign topic to include processing
> info for generalization/specialization use case
>
> Thanks, Paul.
>
> I do have one other thought on this -- rather than trying to hide
> foreign content during generalization, what if we export it --
> essentially, turn it into an imbedded object? Others have pointed out
> that foreign content is really an inline object, so this seems to make
> sense architecturally. We could pretty easily turn this:
> <math class="+ topic/foreign mathml/math ">
>   mathml content here
> </math>
>
> into
> <foreign class="+ topic/foreign mathml/math ">
>   <object data="imbed1.xml" type="DITA-foreign"/> </foreign>
>
> Some additional details on this:
> *  The object element may already be used for alternate content. That
> would not be exported - so you end up with one object pointing to the
> foreign content (type="DITA-foreign" or some equivalent), and one object
> with the alternate content.
> *  Foreign content may use several main elements -- such as
> <foreign><this/><that/></foreign> -- so the exported file should have a
> root <foreign> element to remain valid.
>
> I think the basic approach of exporting the info and using <object> is a
> lot more elegant than processing instructions, both from a DITA
> perspective and from a general XML perspective. It allows me to edit my
> topics with mathml, and then generalize and send them to somebody
> without mathml for further editing/processing. It also doesn't use any
> kludges to hide XML as if it was not XML.
>
> Does this seem like an approach worth pursuing?
>
> Thanks-
>
> Robert D Anderson
> IBM Authoring Tools Development
> Chief Architect, DITA Open Toolkit
> (507) 253-8787, T/L 553-8787
>
> "Grosso, Paul" <pgrosso@ptc.com> wrote on 10/18/2006 08:45:31 AM:
>
> > Actually, I'm okay with 1, 3, or 4, but 4 is what I was suggesting on
> > the telcon and would be my preferred path.
> >
> > ---
> >
> > What are the options with XML Schemas?
> >
> > Am I right to think that--as long as the foreign content is
> > namespaced--we can get things to work by giving the foreign element
> > the appropriate content model (i.e., one that allows any namespaced
> > element)?
> >
> > ---
> >
> > As far as DTDs, I think we could give the foreign element an ANY
> > content model and then all the user would have to do is insert
> > declarations such as
> >
> > <!ELEMENT my:foreign-element ANY>
> >
> > for each foreign element (without explicitly adding references to
> > these elements in any content model), and things would work.
> >
> > That doesn't change your point 1 substantively, but it does reduce
> > "using you foreign DTD module" to merely adding a simple declaration
> > for each of your foreign elements making it much simpler to "share"
> > with others.
> >
> > paul
> >
> > > -----Original Message-----
> > > From: Robert D Anderson [mailto:robander@us.ibm.com]
> > > Sent: Tuesday, 2006 October 17 13:16
> > > To: dita@lists.oasis-open.org
> > > Subject: RE: [dita] Proposal: Update foreign topic to include
> > > processing info for generalization/specialization use case
> > >
> > > It seems like - if we support the foreign and unknown element
> > > - we have
> > > these options when using DTDs:
> > >
> > > 1. We state that, if you use the foreign or unknown elements, you
> > > have no way to share topics with others that do not use your foreign
>
> > > DTD module.
> > > This would be the only way to make a DITA document that cannot be
> > > taken back to the topic type that represents a
> > > least-common-denominator, because you can never share with somebody
> > > that does not use this module.
> > >
> > > 2. We define some way to hide the information when generalizing.
> > > Groups can go back to the most common form; if the common form does
> > > not use the foreign specialization, then they use the alternate
> > > content they (may have) defined with <desc>. So far the only real
> > > proposal for hiding the information is with a PI, which has already
> > > been declared a kludge.
> > >
> > > 3. We state that foreign content is simply discarded during
> > > generalization
> > > - you can't bring it back if you're going to a format that doesn't
> > > support it.
> > >
> > > 4. . We leave it up to each implementation. This means that if you
> > > generalize with one program, other programs may not be able to bring
>
> > > it back. Currently the spec defines how to generalize, which means
> > > that all implementations should be able to work with
> > > specialized/generalized content in the same way.
> > >
> > > Does anybody see any other options? Paul, it sounds like you're
> > > suggesting option one -- does that sound right?
> > >
> > > Thanks-
> > >
> > > Robert D Anderson
> > > IBM Authoring Tools Development
> > > Chief Architect, DITA Open Toolkit
> > > (507) 253-8787, T/L 553-8787
> > >
> > > "Grosso, Paul" <pgrosso@ptc.com> wrote on 10/17/2006 11:48:36 AM:
> > >
> > > >
> > > > > -----Original Message-----
> > > > > From: Eric Sirois [mailto:esirois@ca.ibm.com]
> > > > > Sent: Tuesday, 2006 October 17 09:32
> > > > > To: dita@lists.oasis-open.org
> > > > > Subject: [dita] Proposal: Update foreign topic to include
> > > > > processing info for generalization/specialization use case
> > > > >
> > > > > The foreign content proposal (#35) for incorporating foreign
> > > > > content in DITA did not have a use case that covered what would
> > > > > happen when an DITA document contain foreign content are
> > > > > generalized the content is not longer valid, when using DTDs for
>
> > > > > validation, because the base DTD does not include the foreign
> > > > > vocabularies.
> > > >
> > > > When using DTDs, if it is desired for the generalized content to
> > > > be DTD-valid, then the foreign content elements should be added to
>
> > > > the DTD.
> > > >
> > > > > I propose that we hide the foreign content via a processing
> > > > > instruction in the generalized document. It gets us past the
> > > > > validator issue. The content could then be re-instated during
> > > > > the
> > > specialization
> > > > > process.  Hiding in a comment was discussed, but there is no
> > > > > guarantee that tools keep comments in the documents.
> > > > > Also, it makes
> > > > > reinstating the foreign content during specialization much more
> > > > > difficult.
> > > >
> > > > Putting what should be markup as characters in either a comment or
>
> > > > processing instruction (PI) is quite distasteful to me.
> > > >
> > > > Also, many tools toss PIs too--not ours unless such is explicitly
> > > > requested, but others do.
> > > >
> > > > Note, your generalization process will need to get tricky if the
> > > > content you are trying to hide in a PI contains a "?>" string.
> > > >
> > > > Finally, this all sounds too kludgy and implementation based to me
>
> > > > for a specification.
> > > >
> > > > >
> > > > > In the case where <foreign> contains an <image>, <object>, or
> > > > > <desc>, they should not be hidden within the processing
> > > > > instruction.
> > > > > All content within <unknown> will be hidden in a processing
> > > > > instruction.
> > > >
> > > > paul
> > >
>