How to show math equations with DDoc?

Question

I'd like to use math equations in documentation using DDoc. What's a good way to make it look good?

Something like:

/**
 * Returns x + sqrt(2).
 */
double add_sqrttwo(double x) {
    return x + sqrt(2);
}

A key thing to understand here is that ddoc is just a macro system. It doesn't render _anything_. It can be used to generate html or latex or whatever the text you want by giving the D compiler macro definitions so that it knows what to convert to what, but it doesn't actually render anything. It's the resulting html or latex or whatever that's used to render something. — Jonathan M Davis, Sep 15 '16 at 15:00
The question itself implies that it does. Asking how to make math equations look good in ddoc is nonsensical. It doesn't make them look like anything. It just provides a way for you to mark them up so that they can be converted to text that the generator that you're going to use will understand and do something with beyond display as simple text. It's the html or latex or whatever that takes that text and turns it into something that looks good or not. ddoc has nothing to do with any of that. It's just a macro language. — Jonathan M Davis, Sep 15 '16 at 17:22

johan · Answer 1 · 2016-09-15T17:38:37.537

2

You can import MathJax, and then put the math in-between $ $ or \[ \].

An example:

/**
* Macros:
* DDOC =
* <!DOCTYPE html>
* <html lang="en-US">
* <head>
* <script type="text/javascript" async src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-MML-AM_CHTML"></script>
* <title>$(TITLE)</title>
* </head>
* <body><h1>$(TITLE)</h1>$(BODY)</body>
* </html>
*
*/

module example;

import std.math;

/**
 * Jay! \( a + \sqrt{2} \)
 *
 * You must prefix parameter names with an underscore: \( _x + \sqrt{2} \).
 * 
 */
double add_sqrttwo(double x) {
    return x + sqrt(2.0);
}

edited Sep 15 '16 at 17:38

answered Sep 15 '16 at 14:54

johan

128
7

in your macros, set `DDOC_PSYMBOL=$0` and I think the parameter name will work... – Adam D. Ruppe Sep 15 '16 at 14:56
But then parameter names in other documentation will be broken? – johan Sep 15 '16 at 15:05
Quite the contrary, they will be fixed: DDOC_PSYMBOL is one of the ugliest misfeatures ddoc has, it puts tags around any word that happens to be in scope at the time of the processing. It is the reason why links in Phobos source look like `std/_range.d` for example, and why there's idiocy like `implements the binary search _algorithm` scattered about. It is extremely rarely what you want and very often what you don't... disabling it should be the first thing a ddoc user does (if you want the name highlighted as code, just put backticks around it) – Adam D. Ruppe Sep 15 '16 at 15:07

score 1 · Answer 2 · answered Sep 15 '16 at 14:48

1

I'm afraid DDOC itself cannot do this. You will have to use e.g. Javascript to accomplish this or pre-generate them as images.

answered Sep 15 '16 at 14:48

Richard Andrew Cattermole

464
2
8

score 0 · Answer 3 · answered Sep 15 '16 at 14:49

If you are targeting HTML, there's a few options, though none are ddoc per se: you can link to an image with the formula (<img src="...">), you can put tags around it and process later (whether a post processor in your generation step or a Javascript library on the web), or you can try to write MathML in the document https://developer.mozilla.org/en-US/docs/Web/MathML/Authoring ...

You might also try using various unicode characters like returns X + √2 but that's also pretty limited.

But all of these are working around ddoc, not with it. ddoc just can't do it on its own.

How to show math equations with DDoc?

3 Answers3