Worst Phobos documentation evar!

[Adam D. Ruppe via Digitalmars-d]

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.