On Tuesday, 30 December 2014 at 02:13:40 UTC, Andrei Alexandrescu
wrote:
That's not good either because then it works too much. -- Andrei
I'd make an exception for macro definitions themselves, which
gives you a chance to put syntax for the target language, but ALL
user text outside a macro definition should be encoded. That'd
give consistently correct results and anything short of it is
problematic - in web dev, failing to encode virtually anything is
a likely cause of a cross-site scripting vulnerability and tends
to make invalid output code. This is well enough known in the web
development community that it is rare to find anything that
doesn't auto-escape text anymore.
Here's an example which has trouble right now:
/// given "<b>bold text</b>", returns "bold text"
string innerText();
In ddoc today, we wouldn't see the code it is given. You'd see
bold text because the string isn't encoded properly for HTML
output.
If the escapes were run on the input, it would be quickly
transformed and show the right thing.
Now, suppose you actually *want* it to output the literal tag in
HTML. Easy:
/**
Macros:
B=<b>$0</b>
*/
/// given <b>$(B bold text)</b>, returns "bold text"
That looks like what is seen by the end user - no mess of
$(LT)b$(GT), nor any $(XML b) stuff making it harder to see what
it is meant to be, and gives the flexibility to customize output
code.
The correct code from that in HTML would be:
<b><b>bold text</b></b>
The correct code for that in RTF is
<b>{\b bold text}</b>
You can generate RTF from the source by just changing:
Macros:
B={\b $0}
ESCAPES=
(rtf does have a couple escapes, I think {} and \ need to be done
there, but I'm pretty sure <>&" do not.)
And changing nothing else.
