[Dlang-internal] Potential changes to DDoc
Adam D. Ruppe
destructionator at gmail.com
Sat Feb 3 05:16:26 UTC 2018
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.
More information about the Dlang-internal
mailing list