On Wednesday, 27 February 2013 at 01:03:44 UTC, Walter Bright
wrote:
It's not actually a feature of ddoc at all. Ddoc just transmits
its input to its output, expanding macros along the way.
The problem with that is it makes it extremely inconvenient to
document a html library, and *impossible* to output correct data
in formats unknown to the original author. You say outputting to
different formats is a selling point, but that just isn't true.
Consider this simple comment:
/// Given "<b>text</b>", returns "text"
The most correct output for html is:
Given "<b&rt;text</b&rt;", returns
"text"
Now, suppose we want our ddoc to output... say, json, just to
pull an easy to show example. It *should* be:
"Given \"<b>text<\/b>\", returns \"text\""
In json, the quotes need to be escaped and it is common to also
escape the forward slash, so that's what we want. In html, we
encode quotes differently and should also encode < and >.
But, there's no way to actually do that with ddoc's macros. If we
wanted our ddoc to output json, we'd have to write:
Given $(QUOTE)<b>text<$(SLASH)b>
well you get the idea. And now if we want it to work for both
html AND json, we're writing:
$(QUOTE)$(LT)b$(GT)text$(LT)$(SLASH)b$(GR)
And obviously, that's absurd. What was a readable comment (which
ddoc is supposed to aspire to) is now a hideous mess of macros.
So, you say "nobody would output ddoc to json", but this is just
one easy example with different encoding rules than html. LaTeX
I'm pretty sure needs you to escape the backslash. I'm not sure,
I've barely used latex, so I wouldn't use those macros in my own
code.
What if somebody else wants to apply his set of latex macros to
my code file expecting it to just work? It probably won't.
And, again, this is very easy to solve in the vast majority of
cases: put that ESCAPES macro to good use by running it over the
input data ASAP. Then the data will be properly encoded for
whatever formats we need, without needing these bad preemptive
macros.
