ddoc changes

[Adam D. Ruppe]

ddoc has some flaws that I'd like to fix.

The first one is that it passes stuff directly to the output,
without encoding the characters.

Consider the following comment, that you might see in a html
library:

/// Given this html: <b>bold</b>, you can assert(element.tagName 
== "b");


You don't see <b>bold</b> in the ddoc output. You see bold text. 
That's
wrong.

   a) It makes documenting html things a huge pain
   b) It ties ddoc to one particular output.

      Suppose I want to output this to pdf or something. It won't
      have the same content there; you'll see <b> (as I intended),
      which is different than html output.

   c) It encourages non-portable documentation. You might write 
html
      in there intending to render it, which obviously won't work
      right for non-html output.

      Suppose you manually encode it. $(LT)b$(GT)bold$(LT)/$(GT).

      Not only is that hideous - not readable anymore in source 
form -
      it is *still* wrong for certain output! What if the / needed 
to
      be escaped for my other format? Are you going to make every
      character a macro, just in case someone needs it?


My proposal is to encode all content, before macro expansion,
using an escape table.

/**
Macros:
BOLD=<b>$1</b>
ESCAPES = \
     /</</\
     />/>/\
     /&/&/


I can now write <b>html</b> and show the content correctly,
without breaking the $(BOLD bold macro).
*/


If you want to output html code to be interpreted by the browser,
you must use a macro instead of writing it directly in the source.


Downside of this implementation is stuff in the macros is never
escaped. You might want that... but that's a lot harder to set up.


Pre-encoding all the content before macro expansion is relatively
easy. I've already implemented it in a fork of my compiler; was
actually only a few lines.




Any objections here? I know some old files used direct html in
their ddoc, and this is going to break that, but I think it is
well, well, worth it. I think most new ddoc has been moving away
from that anyway.



For my next post, I'll talk about my plan to fix up the anchors
and attributes too.