[Mono-docs-list] MonoDoc Issues

Jonathan Pryor jonpryor@vt.edu
Sun, 04 Jul 2004 14:17:47 -0400

Issues, bugs, whatever.  They're annoying me. :-)

I'd look into fixing them, but I'm busy painting a house, so...

1.  MonoDoc doesn't like properly escaped XML code.

That's the short of it, anyway.  Nothing is displayed if I have
documentation like this:

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

In other words, if I'm trying to display XML, with the XML properly
escaped (`<' -> &lt;), *nothing* shows up.  All the above gives me is a
table with two rows:

	| .config file Example |
	|                      |

What's really funky is if I change "&lt;configuration&gt;" to "&lt;
configuration&gt;" (i.e. add a space after the opening `<'), I get this:

	| .config file Example |
	| < configuration>     |

So, it seems that the only way to display XML is to have a space after
the opening `<' of XML tags.  Obviously, this is *bad* when I'm trying
to write examples which can be copied/pasted into actual .config files.

Please fix this, as this is blocking several classes worth of
documentation I'd like to add for the Base Class Library
(System.Diagnostics.* classes).

2. The HTML renderer doesn't add spaces when it should.

For an example of this, view the /Mono Documentation/Mono
Handbook/Advanced Topics/Interoperability/Platform Invoke node.  View
the Copyright section (near the end of the document), and you'll see
"...such as blogentries and emailquotations...".  There should be
spaces; it should read "...such as blog entries and email

This appears to be due to this HTML:

        such as <a href="#gc-safe-pinvoke-example">blog</a>
        <a href="#resource-disposal-seealso">entries</a>

So the newline and leading whitespace on the line isn't being converted
into a proper space in the rendering.

 - Jon