[Mono-docs-list] Rendering <example/> blocks

[Jonathan Pryor]

For many moons (literally, I last reported this back on July 4), I've
had a problem with <example/> blocks not rendering content, AT ALL:

	http://lists.ximian.com/archives/public/mono-docs-list/2004-July/001164.html

I later added this to bugzilla:

	http://bugzilla.ximian.com/show_bug.cgi?id=68989

After some additional research, I figured out my problem: it appears to
be due to an interaction between the colorizer and the language I
chose.  Since the contents of example/@lang attribute are used as the
example header, I wanted to choose a title that would be sensible,
leading me to use ".config file" as the language:

	<example lang=".config file">
		...
	</example>

Within mono-ecma.xsl, the contents of the example/code element are
passed to the internal function monodoc:Colorize, which (eventually) is
executed by colorizer.cs:Colorizer.Colorize(), which looks at the
specified language and colorizes the text appropriate, such as for xml,
C#, and vb.

The issue I had was that the Colorizer does more than just color the
text, it also escapes the text so that it's valid HTML.  Consequently,
if you use a comparison operation in your C# example code, it will get
escaped by the Colorizer:

	<example lang="C#"><code>if (a &lt; b) {...}</code></example>

Note that the example code needs to be escaped (as done above). 
Colorizer receives un-escaped text (the &lt; is converted to `<' before
the Colorizer is invoked), so the Colorizer re-escapes it when
generating the colorized HTML.

However, Colorizer only escapes text for languages it recognizes.  This
is why I was never seeing anything -- ".config file" isn't a recognized
language, so it wasn't processed by the colorizer, and thus wasn't ever
escaped for HTML text.  Consequently, the XML used in my example was
passed through unchanged, un-rendered, as it isn't valid HTML.

There are two possible fixes:

1.  Document this as the correct behavior.  This means that any code
using an un-recognized language needs to double-escape any XML entities,
so that it survives the XML -> HTML transition.  This means that my
.config file example would become:

        <example><code lang=".config file">
        &amp;lt;configuration&amp;gt;
          &amp;lt;system.diagnostics&amp;gt;
            &amp;lt;assert logfilename="where I want TraceListener messages to go"/&amp;gt;
          &amp;lt;/system.diagnostics&amp;gt;
        &amp;lt;/configuration&amp;gt;</code></example>

Note that &lt; now becomes &amp;lt;, so that it can be double-converted
into the correct character in the HTML.

I find this ugly-as-sin, but it's livable.

2.  Modify Colorizer.Colorize so that it always escapes XML entities,
even for unrecognized languages.  This seems reasonable and
straightforward to me, but could possibly prevent some functionality
(such as directly emitting HTML into example, such as custom <font/>s,
<span/>s, etc.).

I've done this in a local copy, but I'm unable to test it.  (For reasons
I can't fathom, mono prefers loading the monodoc.dll that's in the GAC
than the newer one in the current directory.  I've got to figure out how
to disable this behavior...)

As a side note, the xml colorizer seems borked within monodoc.  It
doesn't color the text, but inserts the colors inline with the text; for
example, this:

	&lt;configuration&gt;

is rendered in monodoc as:

	blue"><maroon">configurationblue">>

Very non-sensical.

Any opinions on what the correct approach is?

Thanks,
 - Jon