OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

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

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">

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

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

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.

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]