ddoc latex/formulas?

[Andrei Alexandrescu via Digitalmars-d]

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