It often is necessary to include source code in gem README files.  My company, for instance, always puts example code
into our gem README.txt files (see http://configtoolkit.rubyforge.org, for example).  There is no rdoc markup that can
describe a block of text as source code, however.  Thus, in order for the text to be formatted properly, one must declare
it as preformatted.  Generic reformatted text cannot be syntax-highlighted, however (unlike the method source code that
rdoc inlines).

RDoc should be enhanced with new descriptive markup that can describe source code blocks.  The markup could look like
something this:
<code language=”ruby”>
</code>
although no doubt better markup possibilities can be devised.

Now, RDoc already is capable of driving syntax-highlighting for Ruby code but not for other languages.  Perhaps, based
on the template, rdoc either can parse Ruby code itself, or the template could use a package like
http://code.google.com/p/syntaxhighlighter/, to provide syntax-highlighting for multiple languages.