On 15 September 2016 at 21:39, Andrei Alexandrescu via Digitalmars-d <digitalmars-d@puremagic.com> wrote: > 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!
Right, I'm not sure how I produced this confusion, but I seem to have a knack for that. TL;DR, doxygen has: /** * /f[ ...latex syntax here... /f] */ And like magic, your documentation has maths. I expect to write an equivalent line in my d code, and it works. That is all. So, I totally just presumed this was possible, but below you start talking about 'trivially' (as if it's reasonable to expect me to do ANYTHING at all) defining ddoc macros to produce mathjax or latex output, and I pretty much lost interest again at that point. I dread to think what comes next (I have no idea). I presume you need to produce some method to invoke the tools to generate the images from the latex output, and then embed the image in the generated .html somehow? How does it even work? -D causes a .html file to be produced for each .d file... if you want to emit latex fragments or whatever separately such that you can run latex on it, how do you declare the output for that subset of macros to be a separate output file, and then embed a reference to the resulting images of those outputs into the generated html? If it's not the case that ddoc just does this stuff, then I think we have work to do. Assuming this doesn't already 'just work' as I previously thought, perhaps building with -D should also output a makefile together with the bundle of .html, .tex, etc, which would invoke any external programs (like latex) to generate graphs or images or whatever and finalise the documentation? My expectation is that adding -D is the same as typing: doxygen doxy.cfg If that's not the case, and we have no plan to reach that point, then I'll happily commit to the position that I'd rather just use doxygen (from a few posts back). > 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. Can you explain the process? These steps: 1. I write above my function: /** \( ...latex syntax... \) */ 2. I compile with -D 3. ....? 4. My doco has formulas rendered nicely to images in it. In my world, whatever step 3 is, is automatic, and requires no user intervention. I would accept a step like: "3.9: user types 'make' to finalise the docs build", which seems reasonable (and quite powerful/flexible).
