Re: [dita] <include> element in base vocabulary for DITA 2.0

[Don Day <donday@donrday.com>]

Since forms were the use case for "xref as UI to a database" in my previous note, here is another way of switching elements into a form-like role (though as I'll explain at the end, this is not a transclusion proposal).

I examined a fixed attribute value a a way to let transforms switch from standard rendition to form-based rendition. To support form-based editing for "The Language of Technical Communication," I used these extensions:

.mod addition for the specialized elements intended to be editable (each had a separate value):
    formtype CDATA 'tloessay'

.ent addition for the extension:
    <!ENTITY xpd-props-d-att "a(props  formtype)">

Proposed match pattern:
    <xsl-template match="section[@formtype='tloessay']">...

So is this an alternative to using "xref for UI to the database," as previously? No, because in this case, an original document is the source but we are switching the behavior of designated elements from "readable HTML" instead to form fields filled with that element's content. This is not transclusion, but role-switching during the rendition. Without an @href or @query attribute for designating non-DITA content, we can't use this method in the same way as demonstrated below for xref as an interface to a database or other non-DITA source. As it turned out, I did not need to rely on @formtype, but left it in the DTD because I think it has future value for letting processors properly handle an element whose sole role is as an input or interaction.

An ideal solution would enable any element to take on a @conref-like query semantic so that it can name the source of the data it provides a viewport for in whatever use case we have in mind. If @conref serves for DITA transclusions, @dataref could be the non-DITA mechanism for creating viewports from any element. Some elements won't make sense as viewports (prolog or body?), but who is to say? Hence, universal is my vote.
--
Don

On 8/2/2016 9:58 AM, Don Day wrote:

During the discussion of this item in the 19 July 2016 TC meeting, I mentioned some experiences I had with transclusion behaviors. My use case was using DITA to represent a form front end to a database. Normally, we edit DITA documents directly. In this case, DITA markup represents form fields that get their content from a database--literally a transclusion aspect. I needed to represent a transclusion query, which is different than a conref query, so @conref was out as a way to model the query. I made peace with xref because @href represents the query semantic, while it still has a conref semantic in the processing role of getting a title as content.

Here are a few lines of a "document-as-form":

<dl id="xpdformdata" outputclass="asForm" spectitle="Add Event" class="- topic/dl ">
<dlentry class="- topic/dlentry ">
	<dt class="- topic/dt ">Event Name:</dt>
	<dd class="- topic/dd ">
		<xref type="head" href="" format="form" class="- topic/xref "/>
	</dd>
</dlentry>
<dlentry class="- topic/dlentry ">
	<dt class="- topic/dt ">Event Type:</dt>
	<dd class="- topic/dd ">
		<xref type="select" href="" format="form" class="- topic/xref ">
 		<data value="conference" class="- topic/data ">Conference</data>
      		<data value="webinar" class="- topic/data ">Webinar</data>
     	 	<data value="meeting" class="- topic/data ">Meeting</data>
    	  	<data value="training" class="- topic/data ">Training Class</data>
    	  	<data value="other" class="- topic/data ">Other</data>
       		</xref>
	</dd>
</dlentry>
...

And notes FWIW from my transform file:

<!-- use xref to represent an input field in a form: xref type="input" href="" format="form"-->
<!-- "Non-DITA targets use standard URL syntax."
    SQL equivalence:
        table = filename
        row = repeating container element (rowType semantic name, e.g. 'users')
        field names = element names
    document(concat($filename,'.xml'))/tables/users/*[name()=$value]
    Our pattern: {$filename}:{$rowType}:{$value}
    In use:     href=""
    get $filename as "dbLoCS", $rowType as "TitlePage", $value as "title"
    XSLT:     <xsl:value-of select="document(concat($filename,'.xml'))/tables/$rowType/*[name()=$value]"/>

CSS sample: render the queried title LIKE a title
input.title {width:100%; font-weight:bold; font-size:1.5em;}
-->

And as rendered (with no data in this case, hence "CREATE" role in database):

From a webinar slide I gave about this process:

Definition list "specialized" to represent forms

• DITA definition list represents regular parts of an HTML form.
• A fully specialized structure would be enforced by editors.
• The displayed document is the live form, interfaces to SQL table.
• Demo: Add Event: document as form (launch here)
• Key takeaways:
  • DITA behaviors apply: instance/reference fields by conref, conditional views, etc..
  • Document as schema defines the data structure, database holds the data.
  • Rendered form can be copied and reused directly in Web applications; "form generation" with style.

The net is that I was able to make peace with xref as a tranclusion element. I used it to transclude SQL field data, but the semantic justifies pulling in any other non-DITA (or DITA) rendition type as well, as long as the application has a standard way of recognizing that rendition role and applying it. This is why I mentioned "viewport" as a way of describing what is happening in this case.

Hoping this helps the discussion.

--
Don

On 6/25/2016 8:51 AM, Chris Nitchie wrote:

The <coderef> attribute is a transclusion element – it loads the referenced file and places its contents as CDATA at the location of the referencing element. However, <coderef> is a specialization of <xref>, which is not a transclusion element. That is, the specialization-based fallback behavior for <coderef> is fundamentally incompatible with the expected processing. The same is true for svgref and mathmlref. The only way for people other than the TC to create similar transclusion elements via specialization is to specialize from one of those, or customize their processors to do the right thing with their element.

 

For DITA 2.0, I suggest we add an <include> element to the base vocabulary to act as a base for specialization for these kinds of elements.

 

<include href="" format=”format” parse=”xml|text”>

  <fallback>Fallback content here</fallback>

</include>

 

This is roughly modeled on xinclude, but without the need for the namespace, and with @class so it can be used as a base for specialization. (And, of course, @keyref-capable.)

 

Chris

--

Don R. Day
Founding Chair, OASIS DITA Technical Committee (current version: DITA 1.3)
LinkedIn: donrday   Twitter: @donrday
About.me: Don R. Day   Skype: don.r.day

"Where is the wisdom we have lost in knowledge?
Where is the knowledge we have lost in information?"
--T.S. Eliot

Virus-free. www.avast.com

--

Don R. Day
Founding Chair, OASIS DITA Technical Committee (current version: DITA 1.3)
LinkedIn: donrday   Twitter: @donrday
About.me: Don R. Day   Skype: don.r.day

"Where is the wisdom we have lost in knowledge?
Where is the knowledge we have lost in information?"
--T.S. Eliot

Virus-free. www.avast.com