[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
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]