Re: DOCBOOK: Inserting external code into docbook

[Bob Stayton <bobs@caldera.com>]

On Wed, Oct 23, 2002 at 05:42:46PM +0200, Joachim Ziegler wrote:
> According to question 26 in the DocBook Markup FAQ, I tried the following:
> 
> ------------------------------
> (Bob Stayton says)
> 
> You can use following construct to include external code.
> 
> You only need the inlinemediaobject wrapper if you are using 4.1.2.
> 
>       <programlisting><inlinemediaobject>
>           <textobject>
>             <textdata fileref="yourfile.txt"/>
>           </textobject>
>         </inlinemediaobject></programlisting>
> ------------------------------
> 
> I am using 4.1.2 but I get the following errors:
> 
> Pythonbuch.xml:51: validity error: No declaration for attribute fileref on 
> element textdata
>             <textdata fileref="yourfile.txt"/>
>                                             ^
> Pythonbuch.xml:51: validity error: No declaration for element textdata
>             <textdata fileref="yourfile.txt"/>
>                                              ^
> Pythonbuch.xml:52: validity error: Element textobject content doesn't follow 
> the Dtd
> Expecting (objectinfo? , (phrase | calloutlist | glosslist | itemizedlist | 
> orderedlist | segmentedlist | simplelist | variablelist | caution | important 
> | note | tip | warning | literallayout | programlisting | programlistingco | 
> screen | screenco | screenshot | formalpara | para | simpara | blockquote+)), 
> got (textdata )
> 
> 
> What's the preferred way to include external program listings in a DocBook 
> document?
> BTW: I don't understand the semantics of the above nesting of elements.
 
The FAQ misquotes the mail thread.  I didn't supply
the incorrect usage for 4.1.2, I just provided the
way to do it for 4.2 using textobject.  In the 4.1.2
DTD, inlinemediaobject does not support
textobject by itself, and textdata is not
even an element in 4.1.2.

Looking back in the archives, it seems that this is how you
do it with 4.1.2:

<programlisting>
  <inlinemediaobject>
    <imageobject>
      <imagedata fileref="myfunc.c" format="linespecific"/>
    </imageobject>
  </inlinemediaobject>
<programlisting>

This is processed by an XSLT extension function to insert
text from a file and escape the XML markup characters. Such
extension functions are available for Saxon and Xalan, but
not currently for xsltproc. To enable this extension, you
have to set two parameters, either in your customization
layer or on the command line. The parameters are
use.extensions=1 and textinsert.extension=1. Both must be
set for it to work.
-- 

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