Adding Markdown to Ddoc

[H. S. Teoh]

On Wed, Dec 06, 2017 at 02:42:49PM -0500, Andrei Alexandrescu via Digitalmars-d wrote:
> On 12/06/2017 01:14 PM, H. S. Teoh wrote:
> > This "feature" has been the source of countless Phobos and dlang.org
> > bugs, leading to time-wasting churn of changing `someword` into
> > `_someword`, just to suppress the automatic change.
> 
> Isn't that controlled via a macro? We should just redefine the macro
> to return its argument unchanged. -- Andrei

Yes, the macro is DDOC_PARAM.  However, this macro is emitted from two
places in ddmd/doc.d: one in highlightText(), where we'd like to
suppress it, and the other in highlightCode(), where we WANT the
highlighting.  Ergo, there is no way to selectively disable it only in
running text without also killing any highlighting it may have had in
code snippets, where it is wanted.

Perhaps a possible workaround is to use a shim in highlightText(), say,
instead of using DDOC_PARAM, have it emit DDOC_PARAM_IN_TEXT, the latter
of which passes its argument to DDOC_PARAM.  Then to selectively disable
it, we simply redefine DDOC_PARAM_IN_TEXT to return the parameter
unchanged. (And highlightCode() will continue to emit DDOC_PARAM
directly, so the highlighting will still work in code snippets.)

This fancy dance seems completely redundant, though.  If we wanted to
highlight the parameter in running text, we can already use the new
backtick syntax `paramName`. There's really no added value in
introducing yet another default macro DDOC_PARAM_IN_TEXT with a default
definition that, most of the time, people don't even want anyway.


T

-- 
They pretend to pay us, and we pretend to work. -- Russian saying