Re: DOCBOOK: RFE #480954: Extend textobject to insert external files

[Bob Stayton <bobs@caldera.com>]

On Tue, Feb 05, 2002 at 04:12:55PM -0500, Norman Walsh wrote:
> Here is a revised proposal for this RFE.
> 
> Proposal: extend textobject to allow references to external text files
> 
> The following trick is a common way to insert external sources
> directly into a DocBook document:
> 
> <inlinemediaobject>
> <imageobject>
> <imagedata format="linespecific" fileref="filename"/>
> </imageobject>
> </inlinemediaobject>
> 
> Several people have suggested that it would make more sense to
> allow a <textobject> to do this:
> 
> <inlinemediaobject>
> <textobject>
> <textdata fileref="filename"/>
> </textobject>
> </inlinemediaobject>
> 
> This proposal is superior to relying on XInclude for this
> functionality for three reasons.
> 
> 1. It's the logical extension of existing DocBook features and
> replaces a hack with proper semantic markup.
> 
> 2. It will allow entityref, which is possibly a requirement for some
> authors (and is not provided by XInclude).
> 
> 3. XInclude will require namespace support in DocBook. This is
> probably a minor inconvenience for XML, but could potentially be
> troubling for SGMLers.
> 
> I propose:
> 
> 1. Change the content model of textobject to:
> 
> <!ELEMENT textobject (objectinfo?, (phrase|textdata|(%textobject.mix;)+))>
> 
> 2. Add a textdata element:
> 
> <!ENTITY % local.textdata.attrib "">
> <!ENTITY % textdata.attrib
> 	"
> 	entityref	ENTITY		#IMPLIED
> 	fileref 	CDATA		#IMPLIED
> 	%local.textdata.attrib;"
> >
> 
> <!ELEMENT textdata EMPTY>
> <!ATTLIST textdata
> 		encoding	CDATA	#IMPLIED
> 		%common.attrib;
> 		%textdata.attrib;
> 		%textdata.role.attrib;
> >
> 
> The encoding attribute indicates the encoding of the file to be
> included. If not present, the system is expected to determine it by
> whatever means it can.
> 
> The textdata element does not have format or srccredit attributes.
> 
> 3. Allow textobject as the only child of {inline}mediaobject. (Currently
> the media objects require at least one image, audio, or video.
> 
> That's the minimum required, I think. It would also be possible to
> allow <textobject> or <textdata> in more content models (to avoid the
> somewhat odd <inlinemediaobject> wrapper inside, for example,
> <programlisting>. Perhaps textobject should be allowed anywhere
> inlinemediaobject is allowed...but that would be a separate proposal :-)

I'm generally supportive of this approach to including
text files as valid objects.  But I question its inclusion
in inlinemediaobject.  Consider that the textobject is
to be linespecific, that is, needs to preserve
whitespace.  What is it doing inline?  Surely you don't
expect to put a linespecific text object in the middle of a
para.  

It's true that textobject is already a valid child of
inlinemediaobject, but wasn't that to permit a text phrase
to be inserted in output media that don't support
graphics?  The textobject content model does include
larger elements like para, lists, and even blockquote,
but those would more likely be used in a mediaobject,
not an inlinemediaobject that is used within a para.

I think this idea of file inclusions inside
inlinemediaobject came about because people originally wanted to
include a text object inside programlisting and
literallayout, and those elements only allow
inlinemediaobject, not mediaobject.  But inside
those wrappers, linespecific is already turned on,
so it really isn't "inline".

I suggest adding textobject and textdata as valid children of
programlisting and literallayout.  I think that would
satisfy the original need for literal text file inclusion.  
Allowing it to be the only child of mediaobject as you
propose also makes sense.  You can allow it for inlinemediaobject,
but I think it would have limited use once programlisting
and literallayout can have it directly.

-- 

Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
Caldera International, Inc.                 fax:   (831) 429-1887
                                            email: bobs@caldera.com