RE: [dita] foreign element description issue (non-XML?)

Following
some off-list discussion between Kris, Gershon, Paul, and me here is another
suggestion:

 

The <foreign> element allows the
introduction of non-DITA content, for example, MathML, SVG, or Rich Text Format
(RTF). The <foreign> element or a specialization may contain more than
one type of non-DITA content or a mix of DITA and non-DITA content.
Specialization of the <foreign> element generally is implemented as a
domain, but architects looking for more control over the content may implement
foreign vocabularies as structural specializations.

 

This
wording is similar to the suggested wording that Kris proposed a few days ago,
but it is less directive in terms of processing. With the previous proposed
wording I worried that we were placing new requirements on processors that will
be difficult or impossible to implement for all of the possible non-DITA
content that might be included within the <foreign> element or a
specialization.

 

Whatever
wording we finally agree on is intended to replace the current (and much more
detailed) wording in the draft 1.2 spec.

 

Here
in reverse order are the various suggestions that we’ve been working our
way through to get to this point:

 

Kris’s
proposal from 28 December:

 

The <foreign> element allows the
introduction of non-DITA content, for example, MathML, SVG, or Rich Text Format
(RTF). If the <foreign> element contains more than one type of non-DITA
content, processors /should/ render all the content types. Specialization of
the <foreign> element generally is implemented as a domain, but
architects looking for more control over the content can implement foreign
vocabularies as structural specializations.

 

Paul’s
suggested wording from 17 December:

 

The <foreign> element allows the
introduction of non-DITA content such as MathML, SVG, or some textual data
format. If <foreign> contains more than one alternative content element,
they should all be processed. Specialization of <foreign> should be
implemented as a domain, but architects looking for more control over the
content may implement foreign vocabularies as structural specializations.

 

From the 3rd
review draft of the DITA 1.2 Language Reference section on the <foreign>
element under Specialization elements
(this is the material that would be replaced):

The <foreign>
element allows content that would otherwise be stored separately and used via
an <object> element to be contained within a DITA document. The content
may be XML or non-XML, such as MathML, SVG, or some non-XML data format. If
<foreign> contains more than one alternative content element, they will
all be processed. Specialization of <foreign> should be implemented as a
domain, but architects looking for more control over the content can implement
foreign vocabularies as structural specializations 

The default
behavior for <foreign> is to try to display the content. If the processor
cannot render the content, it may emit a warning.

Base
processing attempts to display <foreign> content unless otherwise
instructed.

The enabler
of the foreign vocabulary must provide the processing and override the base
processing for <foreign>. 

 
If <foreign> contains more
     than one alternative content element, they will all be processed. In the
     case of <desc> they will be concatenated in a similar way to
     <section>, but with no title (analogous to <div> in HTML). 

 
If alternate content is desired,
     specialize the <desc> element to contain it. This specialization of
     <desc> will be used within the element specialized from
     <foreign>. Such alternate content must of course be valid wherever
     the <foreign> specialization is valid. 

 
If no <desc>,
     <object>, or <image> element is found within an instance of
     the <foreign> element, the base processing may emit a warning about
     the absence of processable content. 

 
The base processing for
     <object> can emit the content of <foreign> as a file at the
     location specified by the data attribute of the <object> element.
     The <object> element should have a data attribute or a <foreign>
     sub-element but not both. In the event that an <object> element
     contains both a data attribute and an <foreign> sub-element the
     processing system will ignore one of them. 

 

From
the DITA 1.1 Language Reference section on the <foreign> element in the
chapter on Miscellaneous elements:

The <foreign> element is an open extension that allows information
architects to incorporate existing standard vocabularies for non-textual
content. like MathML and SVG, as inline objects. If <foreign> contains
more than one alternative content element, they will all be processed.
Specialization of <foreign> should be implemented as a domain, but for
those looking for more control over the content can implement foreign
vocabulary as an element specialization.

 
-Jeff

 

> -----Original Message-----

> From: Kristen James Eberlein
[mailto:]

> Sent: Monday, December 28, 2009 10:40 AM

> To: dita

> Subject: Re: [dita] foreign element description
issue (non-XML?)

> 

> How about the following wording:

> 

> The <foreign> element allows the introduction
of non-DITA content, for

> example, MathML, SVG, or Rich Text Format (RTF). If
the <foreign>

> element contains more than one type of non-DITA
content, processors

> /should/ render all the content types. Specialization
of the <foreign>

> element generally is implemented as a domain, but
architects looking

> for more control over the content can implement
foreign vocabularies as

> structural specializations.

> 

> Kris

> 

> Grosso, Paul wrote:

> > See my suggested wording at the bottom of this
email.

> >

> > <snipped>

> <kje>a lot of content snipped</kje>

> >

> >>

> >> The <foreign> element allows the
introduction of non-DITA content

> such

> >> as MathML, SVG, or some textual data
format. If <foreign> contains

> more than one alternative content element, they
should all be processed.

> >> Specialization of <foreign> should be
implemented as a domain, but

> >> architects looking for more control over
the content may implement

> >> foreign vocabularies as structural
specializations.