ddoc latex/formulas?

[Andrei Alexandrescu via Digitalmars-d]

On 9/15/16 5:50 AM, Johan Engelen wrote:
> On Wednesday, 14 September 2016 at 11:36:11 UTC, Andrei Alexandrescu wrote:
>> On 9/14/16 1:50 AM, Manu via Digitalmars-d wrote:
>>> Can we produce formulas, or latex in ddoc? Are there any examples in
>>> phobos I can refer to?
>>
>> https://github.com/dlang/dlang.org/blob/master/latex.ddoc
>>
>> That's the macros file for generating the language spec in LaTeX format.
>
> I think what the man is asking for is a way to write formulas in DDoc,
> regardless of output format. Foremost, the math should display well on
> dlang.org.

I see. So he's referring to LaTeX macros as an _input_ method, not as a 
_generated_ conduit. Thanks!

A good answer to that would seem www.mathjax.org. I defined the DIP1000 
semantics (bunch of judgments and greeks) in a ddoc file that uses 
mathjax. For a while (until crunch mode set in) I've used mathjax for 
https://arxiv.org/abs/1606.00484. I have a BigO paper (not yet 
published) that also uses MathJAX for producing consistent LaTeX/PDF and 
HTML documents from the same source.

> If you look at https://dlang.org/phobos/std_mathspecial.html#.gamma,
> there is some math there. But then if you look at the DDoc source,
> https://github.com/dlang/phobos/blob/master/std/mathspecial.d, it's
> pretty terrible how to get it done, and it is very limited (how would
> you get "sqrt(x+y)" to display well, or probably what Manu wants, how to
> get matrix math to display well?).

Here there seems to be a mix of input syntax and rendering being 
discussed. This confuses the living daylight of me again. Let me make 
sure I understand matters correctly:

* ddoc has absolutely nada notion of rendering. To ask "how do I render 
sqrt and aligned matrices with ddoc" does not compute. Is there 
agreement on that?

* mathjax (and latex from which its input syntax is inspired) offer a 
solution for both input (those \macros) and rendering.

* ddoc may be used with either mathjax or latex without interfering in 
any way. It's just a macro system.

So the way you mention to get some math input in ddoc in mathspecial is:

$(GAMMA)(z) = $(INTEGRATE 0, $(INFIN)) $(POWER t, z-1)$(POWER e, -t) dt

This input can be trivially rendered as mathjax/latex by defining the 
macros suitably. In LaTeX and MathJaX the input would be:

\Gamma(z) = \int_0^\infty \! t^{z-1} e^{-t} \mathrm{d}t

which... does not seem quite a day and night difference IMHO. Though I 
do prefer the latter for math-intensive docs because it's a tad more 
concise.

> A great addition to DDoc would be to allow LaTeX bits, like doxygen
> does, and render it nicely for both web and PDF output. You just mark a
> piece of text as <LatexStartsHere>....<LatexOut>.

We already have that. Just use latex syntax inside \( \) and import 
mathjax if you want to generate HTML, or do nothing else to generate 
LaTeX. I'm doing it all the time in my papers.


Andrei