Re: [dita] Groups - Verbatim inclusions of text (character data) (pre-proposal-1.2.xml) uploaded

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

Hi Deborah,

Deborah_Pickett@moldflow.com wrote on 07/18/2007 10:04:50 PM:
...
> On the gripping hand, could we get away with having authors write:
>   <pre><xi:include href="example1.cxx" encoding="utf-8"
parse="text"/></pre>
> and including a clause in the DITA spec that XInclude processing is
> done early in the piece?

That thought worries me. The main reason is the impact that this could have
on conref. I know that XInclude was considered for DITA early on, but was
not used because it doesn't have features that come with conref, such as
automatic validation of content. My understanding of typical XInclude
processing is that a parser will open the file, evaluate XInclude, and then
validate the result. Tools that evaluate XInclude would work just as well
for text as they would for pointers to a DITA fragment. I am not sure how
DITA could allow xi:include for text but not for XML, or whether the DITA
spec can specify that xi:include should only be processed at a specific
point. (Side note: as valuable as I think it could be, there is not yet a
processing specification with DITA, so I am not sure where we would make
such a statement).

If I'm correct about that, then we could not really limit XInclude to only
some situations. I think this would lead to use of XInclude as a
replacement for conref, partly by tools that already have XInclude support
and don't want to implement conref, and partly by authors that simply see
xi:include as something familiar. DITA users wouldn't realize what was lost
until they modified an xi:include target and (possibly much later) tried to
publish invalid documents. I could be getting carried away, but the
scenario seems likely enough that we shouldn't actively encourage use of
xi:include with DITA.

As to the proposal itself - I think the use case makes sense. The actual
use case is simply the ability to reference external text content that will
be used in the document; an href attribute on the pre element is just one
possible implementation. Another possibility would be an element within the
<pre> content model (or even confined to codeblock) that is similar to the
new longdescref and longquoteref elements we've discussed. We could have
something like <coderef/> that can go anywhere within <codeblock>, which
has semantics equivalent to <xi:include parse="text">.

Any other thoughts?

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


                                                                           
             Deborah_Pickett@m                                             
             oldflow.com                                                   
                                                                        To 
             07/18/2007 10:04          apg@syntext.com                     
             PM                                                         cc 
                                       dita@lists.oasis-open.org           
                                                                   Subject 
                                       Re: [dita] Groups - Verbatim        
                                       inclusions of text (character data) 
                                       (pre-proposal-1.2.xml) uploaded     
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           





apg@syntext.com wrote on 19/07/2007 03:00:43 AM:

> Document Description:
> Provide functionality equivalent to xi:include href="url" type="text" in
DITA,
> for elements specialized from topic/pre. This is needed by authors who
write
> tutorials and alike documents, and need to include external source code
fragments
> (eg examples written in some programming language).

I'm torn about this proposal.

On the one hand, anything that removes the temptation for authors to copy
and paste code from an external source is a good thing.  I'd use this
feature.

On the other hand, I don't know that it goes far enough.  I can see authors
wanting to copy only lines 10-19 of a file, or only the part of the file
corresponding to the Foo::Bar method, or only a fragment of an XML document
(serialized as text).  To encompass all of those we might be better served
by a specialization of <data> that can have such parameters passed to it
(and then processing to grab the fragments, presumably via XSLT 2.0
unparsed-text() calls).

On the gripping hand, could we get away with having authors write:
  <pre><xi:include href="example1.cxx" encoding="utf-8"
parse="text"/></pre>
and including a clause in the DITA spec that XInclude processing is done
early in the piece?

These ideas might not be mutually exclusive.

--
Deborah Pickett
Information Architect, Moldflow Corporation, Melbourne
Deborah_Pickett@moldflow.com