[Dlang-internal] Potential changes to DDoc

[Adam D. Ruppe]

On Tuesday, 23 January 2018 at 21:11:26 UTC, Walter Bright wrote:
> Remember, Ddoc macros are not being removed. For the cases of 
> using some other language,
>
>    $(SOME_OTHER_LANGUAGE
>        ...
>    )
>
> will still work, and will of course work with the inevitable 
> languages that do not have syntax highlighting builtin to Ddoc.

Have you ever actually tried this? If not, please do. Spoiler 
alert! It won't work right. Behold:

Given this D:

---
/++
         $(MY_LANG
                 if(a<foo> < 10) {
                         printf("<i>not</i>\n");
                 }
         );

         Macros:
                 MY_LANG=<pre>$0</pre>
+/
module a;
---


dmd -D a.d will spit out something like this:

```html

     <pre>               if(<code class="code">a</code><foo> < 
10) {
                         printf("<i>not</i>\n");
                 }
         </pre>

```


That won't render anything remotely close to what it should. The 
printf contents will come out as italic instead of showing the 
original code. It will incorrectly highlight the variable `a` 
because dmd thought it was referring to the module name `a` (this 
is ddoc's biggest misfeature PLEASE REMOVE IT FOR THE LOVE OF ALL 
THAT IS GOOD!!!).

And most damningly: the C++ template argument, <foo>, gets output 
without any character escaping, causing a browser to think it is 
an html tag, breaking the output entirely.


Of course, you could write:

---
         $(MY_LANG
                 if(a$(LT)foo$(RT) $(LT) 10) {
                         printf("$(LT)i$(RT)not$(LT)/i$(RT)\n");
                 }
         );
---

but pleeeease, be realistic, that will not be used.


At least the ``` block, like the --- and existing `code` 
sections, could automatically escape those characters and 
suppress other ddoc processing inside.



As I constantly remind people, `foo` is NOT equivalent to $(D 
foo) and does NOT simply rewrite one into the other. It also 
performs output character replacement (like ---) and THAT is why 
I added that code in the first place. The shorthand syntax of 
`foo` vs $(D foo) was a side-effect; the real goal was this 
escaping. (of course, everyone loves the syntax too...)

The same reasoning would apply to the ``` blocks.