dita — archive

[Don Day]

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