Re: Example glade files in document

[Dan Mueth <d-mueth uchicago edu>]

On Tue, 31 Oct 2000, Ali Abdin wrote:

> * Dan Mueth (d-mueth uchicago edu) wrote at 01:39 on 31/10/00:
> > 
> > On Sun, 29 Oct 2000, Alexander Kirillov wrote:
> > 
> > > On Sat, Oct 28, 2000 at 01:32:16PM -0500, Federico Mena Quintero wrote:
> > > > 
> > > > I want to have an appendix with the example Glade files.  I tried
> > > > creating a SYSTEM entity pointing to my example .glade file, and then
> > > > including it in a <literallayout>.  Unfortunately, the .glade file has
> > > > its own XML-like tags and thus Jade gets very confused when it slurps
> > > > it into the SGML document.
> > > > 
> > > > My question is, how do I include a plain text file into the SGML
> > > > document without having to massage it by hand?
> > > 
> > > 
> > > We had similar problem when including templates into GDP handbook. The
> > > solution we used is rather clumsy, but I know of no better
> > > one. Namely: in addition to file.glade, create also file.glade.cdata
> > > which is
> > > <!CDATA[
> > > (cut-and-paste your file.glade)
> > > ]]
> > > 
> > > and now you can include this file as entity. 
> > > Stupid thing is, you have 2 almost identical files, which have to be
> > > synced manually - but I know no better solution. 
> > 
> > With the GDP Handbook, we have file.glade.cdata automatically generated
> > from file.glade by the Makefile.  This makes things marginally simpler
> > since you don't have to remember to manually synchronize them all the
> > time.
> 
> Ummm - why don't you just INCLUDE the 'file.glade' as an entity?
> 
> So 'file.glade' would be included by 'file.glade.cdata' which would be
> included by 'docfile.sgml'? Would this work?
> 
> 
> If not, why not just put the CDATA tags in the SGML document, and include
> file.glade as an entity?

This is considered a "marked section" which does not get the usual
processing that the rest of the document gets. The "stuff" in

<!CDATA[
stuff
]]

is completely protected, so any markup or entities in here are ignored and
just treated as character data(CDATA).  Thus, putting an entity inside
won't work (unless you want to show how to type an entity in XML and not
have the entity processed).

So, what we do is use

<programlisting>&MY-ENTITY</programlisting>

where the entity (in this case MY-ENTITY) is your document (eg. XML doc, C
program, etc. ) with a top line: 
<![CDATA[

and bottom line:
]]>


In many cases you don't have to protect your program listing with the
marked section though if it doesn't have anything that looks like XML in
it.  DocBook docs and Glade XML files are cases where you definitely need
the CDATA marked section.

For more info, see: http://www.docbook.org/tdg/html/ch01.html#AEN927
and http://www.docbook.org/tdg/html/programlisting.html

Dan