More ddoc complaints

[Adam D. Ruppe]

On Monday, 9 April 2012 at 11:05:10 UTC, Stewart Gordon wrote:
> What have you done - just made it convert < > & in 
> documentation comments to < > & before processing?

In ddoc's source code, there was a macro called ESCAPES
already, but it wasn't actually used.

My patch enables the use of that macro and runs the input
text, before macro processing, through it.

The default is this:
ESCAPES = /</</
           />/>/
           /&/&/

(check out doc.c in dmd's source, it is already there)

And you can redefine it to whatever you want in your
macro file.

My patch also removes other html specific processing
in the compiler, since I'm pretty sure it is all
obsolete with an escaping run.


If you want to output html, you just make a macro:

B = <b>$1</b>

and that still works.

> What is the user who wants some output format other than HTML 
> or XML to do?

That's the beauty of the ESCAPES macro - you can
redefine it however you want.

> Create LT, GT and AMP macros and use them in your code examples.

There's two problems with that: 1) it is hideous
and 2) what if the user wants some format other
than html?

Suppose your format escapes \. Should I defensively
make a $(BACKSLASH) macro too?

What if a dot is special?

And so on, the only correct solution is proper
escaping, and as an added bonus, it looks infinitely
better in source!