Allowing docbook markup in inline docs (3)

["Matthias Clasen" <matthiasc poet de>]

Here is another problem you run into when trying to put
more serious docs inline. A very simple example like
the following

<informalexample>
<programlisting>
#include "foo"

while (TRUE) do foo();

</programlisting>
</informalexample>

Comes out as unintelligable tag soup:

<para>
<informalexample>
<programlisting>
<type><replaceable><link
linkend="include">include</link></replaceable></type> "foo"
</para>
<para>
while (TRUE) do <function><link linkend="foo">foo</link>()</function>;
</para>
<para>
</programlisting>
</informalexample></para>

The problems are:
1) blank-line separated pieces of text are blindly surrounded by <para>
</para>.
2) the expansion of abbreviations is done everywhere.

I could imagine some things to improve this situation:
1) Don't add para tags if the text chunk starts with a tag.
2) Add some entities to allow suppressing of #, @, () expansion:
<!ENTITY hash    CDATA "#" >
<!ENTITY at      CDATA "@" >
<!ENTITY percent CDATA "%" >
<!ENTITY parens  CDATA "()" >
<!ENTITY space   CDATA " " >

Then we could write the example above as

<informalexample>
<programlisting>
&hash;include "foo"
&space;
while (TRUE) do foo&parens;;
&space;
</programlisting>
</informalexample>

The &space; entities are only necessary to prevent
para insertion inside the example. Actually, I think putting para
tags around the informalexample would not be a problem.

Matthias