Re: [docbook-apps] textobject/textdata for external program code

[Rob Exley <rob.exley@equifax.com>]

Thanks Bob,

I have only had mixed success with this, see below...

BTW I assume you are the same Bob Stayton who has written 'Using the
DocBook XSL Stylesheets' http://www.sagehill.net/xml/docbookxsl/. I only
found this the other day and already think it is one of the most useful
resources I have yet found on publishing DocBook resources. Thanks.

On Thu, 2003-06-12 at 17:38, Bob Stayton wrote:
> On Thu, Jun 12, 2003 at 04:38:23PM +0100, Rob.Exley@equifax.com wrote:
> > I am currently writing a technical spec using DocBook XML 4.2 and
> > publishing using Cocoon 2.0.4 with Saxon 6.5.2 and docbook-xsl-1.61.2.
> > 
> > I have been experiencing problems including external DTD files (and xml
> > documents) within an appendix of the document and have finally succeeded by
> > using a textdata element within a textobject nested in a programlisting
> > element. However I seem to have encountered two problems specifically with
> > this:
> > 
> > I have been forced to use the fileref attribute of the textdata object and
> > hard-code the path to the external document. I would ideally have liked to
> > us an entityref and then define all my external entities at the top of the
> > document. This however seem to give me blank output for both html and pdf
> > output. The following was my original document snippet
> > 
> > <?xml version="1.0"?>
> > <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
> > "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
> > <!ENTITY generic-request.dtd SYSTEM
> > "/home/r_exley/tmp/code/xml/generic-request.dtd">
> > ]>
> > .
> > .
> > .
> > <section>
> >   <title>generic-request.dtd</title>
> >   <programlisting>
> >     <textobject>
> >       <textdata entityref="generic-request.dtd" />
> >     </textobject>
> >   </programlisting>
> > </section>
> > .
> > .
> > .
> > 
> > I have since replaced the textdata element in the above with
> > 
> >       <textdata fileref="/home/r_exley/tmp/code/xml/generic-request.dtd" />
> > 
> > and this gives me the expected output. My assumption for using the
> > entityref approach was that I could extend this to make advantage of
> > catalogs.
> 
> The entity pointed to by an entityref must have an NDATA type
> as declared in the DTD. DocBook declares linespecific
> for this, so change your entity declaration to:
> 
> <!ENTITY generic-request.dtd SYSTEM
> "/home/r_exley/tmp/code/xml/generic-request.dtd" NDATA linespecific>
> 
> Then the entityref should work.  The validation process
> should have pointed out this problem.
> 

unfortunately this doesn't seem to work unless I have done something
else wrong. I tried changing one of my elements to using an entityref
and then changing the entity declaration as you suggested but it still
just gave me blank output for the section in question.

<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY generic-dn-request.dtd SYSTEM
"/home/r_exley/tmp/code/xml/generic-dn-request.dtd" NDATA linespecific>
<!ENTITY ntg-base-request.ent SYSTEM
"/home/r_exley/tmp/code/xml/ntg-base-request.ent">
<!ENTITY dn-base-request.ent SYSTEM
"/home/r_exley/tmp/code/xml/dn-base-request.ent">
<!ENTITY dn-person.ent SYSTEM
"/home/r_exley/tmp/code/xml/dn-person.ent">
<!ENTITY generic-dn-response.dtd SYSTEM
"/home/r_exley/tmp/code/xml/generic-dn-response.dtd">
<!ENTITY ntg-base-response.ent SYSTEM
"/home/r_exley/tmp/code/xml/ntg-base-response.ent">
<!ENTITY dn-base-response.ent SYSTEM
"/home/r_exley/tmp/code/xml/dn-base-response.ent">
<!ENTITY generic-catalog SYSTEM
"/home/r_exley/tmp/code/xml/generic-catalog">
]>
 
<book>
.
.
.
      <section>
        <title>generic-dn-request.dtd</title>
        <programlisting><textobject><textdata
entityref="generic-dn-request.dtd" /></textobject></programlisting>

      </section>
                                                                                                                              
      <section>
        <title>ntg-base-request.ent</title>
        <programlisting><textobject><textdata
fileref="/home/r_exley/tmp/code/xml/ntg-base-request.ent"/></textobject></programlisting>
      </section>
.
.
.



[sorry about the formatting, I have used 'evolution' to send this and I
seem to be having problems driving the editor without word-wrap kicking
in.]

> <
> > 
> > Also in the pdf output resulting from this, the first line for each
> > included text file is indented, this is somewhat strange and throws the
> > formatting out (and looks ugly). This only occurs in the pdf output, the
> > html output is fine.
> 
> Inside a programlisting element, all white space is preserved,
> including that before and after your textobject.  So change
> it to:
> 
>    <programlisting><textobject>
>         <textdata entityref="generic-request.dtd" />
>       </textobject></programlisting>
> 
> The whitespace inside textobject should be ignored, though.

I got this to work with a little experimentation. I had to make sure
neither the programlisting nor the textdata object had any whitespace
within it to get the desired result. If either contained whitespace then
the resulting inserted DTD text had the first line indented.


-- 
Rob Exley
Senior Technical Consultant
Equifax Plc

e-mail: rob.exley@equifax.com
tel: 01274 759610

This is a digitally signed message part