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.
