Improving ddoc

[Walter Bright via Digitalmars-d]

On 1/1/2015 6:00 AM, Joseph Rushton Wakeling via Digitalmars-d wrote:
> See, this is my point.  $(INTERVAL x .. y) is, to my mind, less clear to read
> _in the source_ than [x, y).

My point is there's ALWAYS going to be some sort of escaping mechanism, and it 
is ALWAYS going to interfere with the look of anyone who wants to use the full 
character set on the keyboard, which IS going to happen whenever you write math 
text.


> If I read $(INTERVAL x .. y) then, OK, I will grasp it's an interval between x
> and y.  But is it the closed interval [x, y], one of the half-open intervals (x,
> y] or [x, y) or the open one (x, y) ... ?

You don't have to call it INTERVAL. You can write your own macro to name it 
whatever works for you. I do it all the time. You can even then change the 
definition of the macro and, for example, have it styled differently (like use a 
different font, different font weight, different color, etc.) I find that very 
handy.

A lot of the complaints about Ddoc clearly stem from people not realizing they 
can create their own macros. It's like not realizing that C code can contain 
custom written functions.

Here's one example that was brought up in the discussion:

    https://github.com/D-Programming-Language/phobos/pull/2828

A custom macro made all the difference. Not only that, it is now easy to switch 
it from a table to a definition list, or have custom styling for it, all without 
messing anything else up. This cannot be done with Markdown.

You might ask "why would we want custom styling"? Turns out that that example is 
a nice one for why not use it.


> I need that kind of precision to document the kind of code I'm writing
> (including phobos contributions), and I would like to be able to read and write
> with that precision explicitly in the source.
> If I need to use a macro
> definition, then the reader has to look up that definition, and you just _know_
> that people are going to use those macros incorrectly, e.g. if we suppose that
> INTERVAL is [x, y), then people will use it in circumstances where they mean [x,
> y] or (x, y) or whatever.
>
> Yes, I could use a right-bracket UTF8 character, but that's finnicky and
> annoying (and potentially runs into other problems for readers, e.g. what if
> someone copy-pastes my ddoc source into a non-UTF8 email?).

Math notation uses a ton of special characters, it's one of the reasons why 
Unicode was invented. Limiting yourself to non-Markdown ascii is extremely 
limiting. Heck, look at this:

https://www.google.com/search?q=latex+math+symbols&biw=1282&bih=897&tbm=isch&tbo=u&source=univ&sa=X&ei=pqqlVLbcM5TkoATv9oGABg&sqi=2&ved=0CDQQsAQ


> And yes, I could
> use [x, y[ or ]x, y] or ]x, y[, but that notation is more specialist and likely
> to be confusing to readers.
>
> I'm sorry, but I can't see it as anything other than a serious flaw of ddoc that
> a super-common character in both code and mathematics has problems being used,
> as itself, inside the documentation markup :-)

Isn't * a super common math character? and |? and +? All of which are markdown 
characters.

The only time the stray paren issue comes up is in the interval notation.