Improving ddoc

[Joseph Rushton Wakeling via Digitalmars-d]

On 01/01/15 21:15, Walter Bright via Digitalmars-d wrote:
> 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.

Yes, I accept that.  I'm just pointing out what I find problematic with this 
particular escaping mechanism, given the documentation needs of the code I'm 
involved with.

I do however still think that using $( ) to delineate start and end of macro 
blocks is a bad choice given the prevalence of ( ) in code.

Before I reply to the rest of your email, I think I should point out two things:

   * I understand that ddoc is a macro system, I understand what that
     means and how flexible and powerful it can be (I've used LaTeX for
     years, and I have created my own custom ddoc macros).  I'm not
     trying to persuade you to give that up.

   * I'm not trying to advocate for you to start supporting markdown,
     although I do understand why some people are.

   * LaTeX maths notation on the other hand ... ;-)
      - actually I'm mostly raising this last point to
        tease you, but there is a serious side; I'll
        explain later in the email.

Anyway, to some details ...

> 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.

Yes, I understand that I can write different macros to mean different things. 
But surely you can understand my point from the previous email, that having 4 
different macros to indicate the different types of intervals, is much less nice 
from a reading/writing point of view than just being able to write, in ASCII, 
[x, y], (x, y], [x, y) and (x, y).

It's not just maths notation either -- this will trigger the 'Stray )' warning too:

     Example:
     --------
     auto u = uniform!"[)"(0.0, 1.0);
     --------

I think we can achieve that simplicity of reading, not just for these two 
examples, but for potentially quite a bit more maths and code, without 
sacrificing any of the things you're interested in keeping.

> 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.

Yes, and nothing I say here should be taken as denying the usefulness or 
desirability of being able to do that.

BTW talking of custom macros and custom styling, that file has something I 
consider to be a horrendous violation of good styling design in it:

     MYREF = <font face='Consolas, "Bitstream Vera Sans Mono", "Andale Mono", 
Monaco, "DejaVu Sans Mono", "Lucida Console", monospace'><a 
href="#.$1">$1</a> </font>

> 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

Sure, but even with unicode, there's a limit to how sanely you can represent a 
complex formula in plain-text.  Personally, this is the point where I'd rather 
be able to use inline LaTeX formulas, because I think most people interested in 
complex formulas will be able to understand that.

Please don't dismiss this idea out of hand: I think there are some handy tools 
we could use to integrate this very well into our documentation system.  Using 
the MathJax javascript makes it pretty easy to embed LaTeX formulas into an HTML 
document:
http://www.mathjax.org/

... and obviously when outputting to LaTeX, it becomes much easier to just hand 
on LaTeX formulas as they are.

If we could do something like,

     $(MATH F(x) = \int_{0}^{10} f(x) dx )

then it would be very nice.  Obviously this won't work notationally quite as-is, 
but I don't see why it shouldn't be possible to find something similar that is 
workable.

(N.B. this is a definite "Dream Wishlist" item, so please don't see it as the 
main concern of my email; if it isn't workable, just tell me that and move on to 
the end of the email, where there is the point I really would like your feedback 
on.)

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

Well, as I'm not arguing for markdown, this may be a moot point.  But I don't 
recall encountering those issues with markdown, because IIRC most markdown use 
of those special characters is quite context dependent: i.e.

    *this produces bold or emphasized text* but x * y * z does not :-)

... so it doesn't complicate maths notation as you might think.  (The above 
works at least with GitHub markdown:-)

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

I get that my example is an edge case that may not be the best motivation for 
you to change how things work.  But here's the other idea I'd like to suggest 
that might help resolve this.

Others have suggested `this` as a shorthand for $(D_CODE ) or whatever.  I'd 
like to suggest that instead `this` be used as a way to indicate to Ddoc: "There 
are no Ddoc macros inside this bit of text, nor will a macro end."

So, for example, I could rewrite my earlier documentation example as:

/**
$(D uniform01) offers a faster generation of random variates than
the equivalent $(D `uniform!"[)"(0.0, 1.0)`) and so may be
preferred for some applications.

Returns:
     Floating-point random variate of type $(D T) drawn from the uniform
     distribution across the half-open interval `[0, 1)`.
  */

... and the "Stray ')'" concerns need not arise, because the `...` blocks 
guarantee that any ')' character they contain is not stray.

Does this sound at all feasible?