Markdownify code syntax from the old $(D code) macros to Markdown (i.e. code)

[wilzbach]

Gets Phobos one step closer to pretty code ;-)

While the detection is easy with a stupid RegExp, I needed to write a small lexer as it's context-sensitive:

$(D foo) -> `foo`
$(D writeln("foo")) -> `writeln("foo` /// <- with a naive RegExp

Ideally DAutoTest shouldn't show any changes.

[adamdruppe]

I'm actually against this, somewhat strongly. The backtick and the $(D ) macros have different semantics on two levels:

• Backticks can not contain embedded HTML (and are not supposed to contain macros, the way I intended it, but the implementation didn't keep to that intention), whereas $(D ...) can. Embedded html is a major ddoc misfeature, but one you need to watch out for in translation. The diff looks ok, but still,

/// `<b>hi</b>`
/// $(D <b>hi</b>)

will render as two different things in dmd today.... (yet as the same thing in ddox today. I call that a bug in ddox!)

• Backticks are generic code and may be a --command-line-arg or a {"config":"sample"} or <xml snippet="" />, whereas $(D) specifically is D code and might be highlighted or cross-referenced differently. Why remove additional useful information that already exists? It is nice to know that it is D as opposed to some other type of code. Granted, phobos uses $(D) in some places for code that isn't actually D (see: std.getopt for example), but it is more right than wrong. Mechanically removing all of them is a net loss of useful information.

Just today, I implemented context-aware cross referencing in dpldocs.info that uses the $(D ...) macro to intelligently look up names. Take a look at this for example: http://dpldocs.info/experimental-docs/std.stdio.File.close.html The links to File and detach are auto-generated thanks to being in a $(D ...) macro, so it could check the imports and get an exact match. (It doesn't link ErrnoException btw because that isn't actually in scope; it is thrown by the selectively-imported errnoEnforce..)

I specifically did not apply that to backticks because they are often used on non-D code (the reason I pushed for them in dmd was to document xml samples in my dom.d...) and attempting name lookup and syntax highlighting there can lead to silly results. It isn't disastrous but it is less than ideal and IMO a step backwards from where we are now. Knowing the language of code snippets leads to more intelligent output.

[andralex]

Yah, prolly we should keep this for single words only for the time being.

[wilzbach]

Yeah you made an excellent case! And there are more important things in this world ;-)

Closing as well.

[andralex]

@wilzbach @adamdruppe I very much appreciate how you handled this. Thanks!!