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

[Deborah_Pickett@moldflow.com]

Robert D Anderson <robander@us.ibm.com> wrote
on 21/07/2007 06:10:56 AM:

> 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. [...]

Oh, me too.  XInclude is an awful lot of rope,
and there is a risk of much foot-shooting if it isn't let into the DITA
world gently.  I felt that it should be mentioned, though.

One thing that XInclude gets right is encoding negotiation
(http://www.w3.org/TR/xinclude/#text-included-items).  The proposal
text is ambiguous about encoding negotiation (it says "using document
encoding"; which document?), perhaps because it doesn't take account
of cases where the included text comes from a source where out-of-band
information already knows the document's encoding (e.g., an HTTP GET).
 I'd prefer to see the proposal list exactly how encoding is to be
handled.  Ditto WRT byte-order marks, whether they are stripped or
not.  Ditto WRT line-end conventions, especially whether the newline
in the final line of the inclusion is to be included.

IMHO the proposal should also make it clear that any
implementation that produces the same effect as XInclude is valid; implementations
aren't required to actually use XInclude.  (For example, I suspect
that DITA-OT will choose to do it in dost.jar rather than rely on a full
XInclude processor.)

> As to the proposal itself - I think the use case
makes sense.
[...]
> 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">.

That would solve the problem of my "other hand".
 You might see optional <data> elements specialized for insertion
into <coderef> as a child:

<codeblock><coderef href=""textfile.txt">
  <firstline>10</firstline>
  <lastline>19</lastline>
</coderef></codeblock>

<codeblock>// Prepend a comment into the codeblock
that isn't in the file.
<cpp-method href=""thing.cpp">
  <signature>Class::Method(int param1,
char *param2)</signature>
  <strip-indent>4</strip-indent>
 <!-- Since all lines in source have four spaces of indentation.
-->
  <highlight>variable<highlight>
 <!-- This variable is discussed in my topic; bold it. -->
</cpp-method></codeblock>

<codeblock><xml-coderef href=""sample.dita">
    <xpath>//*[@id='foo']</xpath>
 <!-- All right, this one is difficult. -->
</xml-coderef></codeblock>

Specialized processing could strip out lines outside
the 10-19 range, or do other postprocessing, after the whole document got
included verbatim in an earlier pipeline stage.  None of this would
need to go into the proposal, of course; what's important is that it becomes
possible for specializers who want it.