Code support is broken

[Dan Groshev]

When I'm pasting this to my overview.edoc:

<pre lang="erlang">
16> ecirca:load(B).
{ok,{ecirca,#Ref<0.0.0.166>,<<>>,<0.48.0>,medium}}
</pre>

I get:

> rebar doc skip_deps=true
==> ecirca (doc)
2991- fatal: {invalid_name,"0.0.0."}
./doc/overview.edoc: at line 6: error in XML parser: {fatal,{{invalid_name,"0.0.0."},
                             {file,file_name_unknown},
                             {line,101},
                             {col,18}}}.
edoc: error in doclet 'edown_doclet': {'EXIT',error}.
ERROR: doc failed while processing /home/si14/repos/ecirca: {'EXIT',error}

And I also can't use Github's variant because of "```-quote ended unexpectedly" error.

[Ulf Wiger]

The problem here is that edoc (via Xmerl) requires the markup to be valid XHTML, and markup is still parsed within pre tags ('pre' just means "preformatted" and tells the parser to preserve whitespace). In this case, the error occurs even before Edown gets a chance to massage the data.

What you can do is either to escape the < and > (as &lt; and &gt; respectively) or to do this:

<pre lang="erlang"><![CDATA[
16> ecirca:load(B).
{ok,{ecirca,#Ref<0.0.0.166>,<<>>,<0.48.0>,medium}}
]]></pre>

using <![CDATA[ ... ]]> as a wrapper to avoid having to escape the source. This should also be reasonably Edoc-compatible (although normal Edoc processing will ignore the lang="erlang" part).

As an aside, Edoc adds the <![CDATA[ ... ]]> wrapper when you use the ... ''' syntax (note though, how Edoc uses different end brackets from Github Markdown), but since it doesn't include any way to indicate the language (and erlang ... ''' would cause the "erlang" bit to end up on a line of its own. This would look funny in normal Edoc and Edown would have to guess that it means that the section should be highlighted as Erlang code).

[Dan Groshev]

Now I see, thank you. Would you mind putting this explanation to README?