Including verbatim text in a document...

[Norman Walsh <ndw@xxxxxxxxxx>]

In the past few weeks/months, I've seen several queries about
how to easily include verbatim text in DocBook documents.
The standard answers,

  <programlisting>
  <![CDATA[
  #include <stdio.h>
  ...
  ]]>
  </programlisting>

and

  <programlisting>
  #include &lt;stdio.h>
  ...
  </programlisting>

leave something to be desired.  There's a lot to be said for the
ability to include text directly from an external file.  This
would allow one to include the actual sources that one is
documenting, for example.

But there's no DocBook element that really has the required
semantic.  There are a few elements that could be extended to
have this semantic using ROLE, but that's also less than
perfect.

In the future, the standard answer to this question will almost
certainly be found in XLink.  But the XLink spec isn't finalized
yet and implementation in advance of the spec in DocBook would
mean supporting yet another linking mechanism in DocBook when
XLink is finalized.

So, in the next release of the DocBook DSSSL Stylesheets, I'm
including support for the following clever trick/dirty hack
(choose one ;-), unless someone talks me out of it.

  <!DOCTYPE para PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
  <!ENTITY program SYSTEM "program.c" CDATA linespecific>
  ]>
  <para>
  Here's my listing:
  <programlisting>
  <inlinegraphic entityref="program"></inlinegraphic>
  </programlisting>
  </para>

Basically, if the ENTITYREF on GRAPHIC/INLINEGRAPHIC has the
LINESPECIFIC notation, I'm going to slurp it up (with James'
read-entity extension in Jade) and spit it out.

This doesn't require walking on the ROLE namespace, which should
be free for the author to use, and doesn't seem like
unreasonable behavior.

Comments?

                                        Cheers,
                                          norm
-- 
Norman Walsh <ndw@xxxxxxxxxx>      | Any sufficiently undocumented code
http://nwalsh.com/                 | is indistinguishable from magic.


 DSSSList info and archive:  http://www.mulberrytech.com/dsssl/dssslist