Adam D. Ruppe
destructionator at gmail.com
Sat Feb 18 14:05:39 PST 2012
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
/// Given this html: <b>bold</b>, you can assert(element.tagName
You don't see <b>bold</b> in the ddoc output. You see bold text.
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
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
it is *still* wrong for certain output! What if the / needed
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.
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.
More information about the Digitalmars-d