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

On Wednesday, 14 September 2016 at 15:49:27 UTC, bachmeier wrote:
> I agree. That's why I quickly gave up on ddoc.

My doc generator just pipes special input text through the latex program to generate an image, which is then inlined in the html:

http://dpldocs.info/experimental-docs/test.html

I'm still not 100% happy with my doc gen and it is moving slowly cuz of other obligations, but this was something I was able to do pretty easily thanks to my willingness to just pipe to a helper program.

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

On 15 September 2016 at 22:40, Adam D. Ruppe via Digitalmars-d <digitalmars-d@puremagic.com> wrote:
> On Wednesday, 14 September 2016 at 15:49:27 UTC, bachmeier wrote:
>>
>> I agree. That's why I quickly gave up on ddoc.
>
>
> My doc generator just pipes special input text through the latex program to generate an image, which is then inlined in the html:
>
> http://dpldocs.info/experimental-docs/test.html

Now we're talking!

> I'm still not 100% happy with my doc gen and it is moving slowly cuz of other obligations, but this was something I was able to do pretty easily thanks to my willingness to just pipe to a helper program.

What does that mean? What's your process to produce this output? Problem is, phobos uses vanilla ddoc... so we need that to do everything we need.

On 09/15/2016 08:40 AM, Adam D. Ruppe wrote:
> On Wednesday, 14 September 2016 at 15:49:27 UTC, bachmeier wrote:
>> I agree. That's why I quickly gave up on ddoc.
>
> My doc generator just pipes special input text through the latex program
> to generate an image, which is then inlined in the html:
>
> http://dpldocs.info/experimental-docs/test.html

Nice. I recall that was the standard solution until a few years ago. It seems the newfangled way to do so uses javascript rendering, see http://tex.stackexchange.com/questions/23804/how-to-incorporate-tex-into-a-website. -- Andrei

On 09/15/2016 08:42 AM, Manu via Digitalmars-d wrote:
> On 15 September 2016 at 21:39, Andrei Alexandrescu via Digitalmars-d
> <digitalmars-d@puremagic.com> wrote:
> 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.

It is pretty much all:

M = \( $0 \)

and then just write $( ... \LaTeX math syntax here ...), or use \( \) directly.

Almost all - you need the include simply because you need to instruct ddoc whether you w, but that can be factored in a standard .ddoc file. This is part of doing business and it becomes a matter of .ddoc libraries, documentation, and user education. If you protest that, I understand but don't agree.

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

It /is/ trivial. Take a look at the source of http://erdani.com/d/DIP1000-typing-baseline.html and at its source at http://pasted.co/7ea68163. Which format would you rather input typing judgments in? (Serious question.)

It literally took me less than a minute to get things going, using zero preexisting support. To folks who can't afford that much time I don't have a solution.

To put in jokingly, it seems to me the question is progressively distilling toward: "How do I type math in ddoc? Note that (a) I don't know ddoc and can't be bothered to learn anything about it; (b) I don't know much LaTeX or related tooling either; (c) I want to do absolutely nothing - everything must be already built in."

We really got to meet somewhere, and "it's unreasonable to expect me to do ANYTHING at all" is not the place to meet. At the minimum you have to be willing to put latex.ddoc in your doc generation command line or something. We can't build in all input syntaxes and all output renderings possible.

> I dread to think what comes next (I have no idea).

How was it?

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

Nope. My command line is (and I swear I'm pasting from my other workspace) is:

dmd ~/d/dlang.org/html.ddoc DIP1000-typing-baseline.dd

I'm including html.ddoc to benefit from possible HTML-specific shortcuts, but I just tried it like this right now and figured the output is identical:

dmd DIP1000-typing-baseline.dd

So this WORKS and it took me A MINUTE to get going. Is this a reasonable bar?

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

Never did that. For the mathjax solution see above. For a pure latex solution that's supposed to be fed to latex, our makefile catenates together the files generated into one large .tex file, which is then fed to latex to generate one pdf. See https://github.com/dlang/dlang.org/blob/master/posix.mak#L311.

> If it's not the case that ddoc just does this stuff, then I think we
> have work to do.

I think it implements a simpler idea to the same effect.

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

That would be interesting, but we need to have a good image of what we want to accomplish.

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

Again, we need to have a clearer image of what the issues are and what we're trying to accomplish. It seems at this point your disposition is based on a web of misunderstanding.

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

Does the explanation above cover this?


Andrei

On 09/15/2016 09:12 AM, Manu via Digitalmars-d wrote:
> On 15 September 2016 at 22:40, Adam D. Ruppe via Digitalmars-d
> <digitalmars-d@puremagic.com> wrote:
>> On Wednesday, 14 September 2016 at 15:49:27 UTC, bachmeier wrote:
>>>
>>> I agree. That's why I quickly gave up on ddoc.
>>
>>
>> My doc generator just pipes special input text through the latex program to
>> generate an image, which is then inlined in the html:
>>
>> http://dpldocs.info/experimental-docs/test.html
>
> Now we're talking!

That strikes me as an inferior solution to what's available today, which is used at http://erdani.com/d/DIP1000-typing-baseline.html.

>> I'm still not 100% happy with my doc gen and it is moving slowly cuz of
>> other obligations, but this was something I was able to do pretty easily
>> thanks to my willingness to just pipe to a helper program.
>
> What does that mean? What's your process to produce this output?
> Problem is, phobos uses vanilla ddoc... so we need that to do
> everything we need.

No, you don't need that.


Andrei

On 09/15/2016 09:46 AM, Andrei Alexandrescu wrote:
> and then just write $( ... \LaTeX math syntax here ...), or use \( \)
> directly.

I meant: $(M ... \LaTeX math syntax here ...)

Andrei

On Thursday, 15 September 2016 at 13:12:05 UTC, Manu wrote:
> What does that mean? What's your process to produce this output?

./adrdox test.d

The program internally runs pipeProcess over to latex to make the image when it sees the $(MATH ....) syntax.

> Problem is, phobos uses vanilla ddoc... so we need that to do everything we need.

Yeah, that's why I forked phobos for my doc project too. Vanilla ddoc is a dead end.

On Thursday, 15 September 2016 at 11:39:13 UTC, Andrei Alexandrescu wrote:
>
> * 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?

D has absolutely no notion of "databases", but I think it's fair to ask "how do I retrieve data from a database using D".
DDoc bare does not need a notion of rendering, but the base system in place (call it the DDoc std lib) does need to present a way for a user to end up with a math equation "rendered" well.

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

Well, I'm pretty sure just typing \( \) and running `dmd -D` is not going to give me the output that I want. Indeed it doesn't.

But, as you write, it's easy to make it happen. Full 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>
*/

/**
* \[
*  \mathbf{V}_1 \times \mathbf{V}_2 =
*   \begin{vmatrix}
*    \mathbf{i} & \mathbf{j} & \mathbf{k} \\
*    \frac{\partial X}{\partial u} & \frac{\partial Y}{\partial u} & 0 \\
*    \frac{\partial X}{\partial v} & \frac{\partial Y}{\partial v} & 0 \\
*   \end{vmatrix}
* \]
*/

module ddoctest;
```

`dmd ddoctest.d -D -o-` produces an HTML file with nice looking math in it.

Now, can we please add this question to stackoverflow, and add this as an answer?
:)