## digitalmars.D - ddoc latex/formulas?

• Manu via Digitalmars-d (2/2) Sep 13 2016 Can we produce formulas, or latex in ddoc? Are there any examples in
• Andrei Alexandrescu (4/6) Sep 14 2016 https://github.com/dlang/dlang.org/blob/master/latex.ddoc
• Manu via Digitalmars-d (13/19) Sep 14 2016 Ah, wow, yeah I actually saw this when I googled for it before posting h...
• jmh530 (6/17) Sep 14 2016 I learned Latex by playing with LyX. You can get things looking
• bachmeier (8/39) Sep 14 2016 I agree. That's why I quickly gave up on ddoc. The macro system
• Adam D. Ruppe (8/9) Sep 15 2016 My doc generator just pipes special input text through the latex
• Manu via Digitalmars-d (6/15) Sep 15 2016 Now we're talking!
• Andrei Alexandrescu (5/23) Sep 15 2016 That strikes me as an inferior solution to what's available today, which...
• bachmeier (6/9) Sep 15 2016 But how did you do that? I think KaTeX may be a better solution
• Andrei Alexandrescu (7/15) Sep 15 2016 See source at http://pasted.co/7ea68163 and Johan's example on SO.
• Manu via Digitalmars-d (5/27) Sep 15 2016 I'm guessing that's mathjax? Strangely, it renders really badly on my
• Johan Engelen (3/12) Sep 16 2016 I believe at least the syntax for the stuff is LaTeX:
• Andrei Alexandrescu (4/7) Sep 16 2016 You may want to check the options discussed at
• Marco Leise (8/14) Sep 16 2016 I don't understand any of it, but it looks really good on
• Andrei Alexandrescu (3/15) Sep 16 2016 Manu, what OS/browser are you using? Could you please post a screenshot
• bachmeier (5/9) Sep 16 2016 Normally this happens when you are not allowing the use of
• Andrei Alexandrescu (5/14) Sep 15 2016 Wait, but I just showed how with vanilla ddoc you can immediately use
• Adam D. Ruppe (17/20) Sep 15 2016 mathjax IS postprocessing via scripting. And better is extremely
• tn (7/15) Sep 16 2016 Yes. I opened the link [1] by Andrei into a new tab, saw some
• Andrei Alexandrescu (3/17) Sep 16 2016 Yah, the whole page is exclusively rendered math, and difficult too. A
• bachmeier (4/9) Sep 16 2016 That is why KaTeX should be used
• Andrei Alexandrescu (4/14) Sep 16 2016 Yah, we should consider that if we get heavily into math. The fixed
• Andrei Alexandrescu (5/10) Sep 15 2016 Nice. I recall that was the standard solution until a few years ago. It
• John Colvin (4/18) Sep 16 2016 Wikipedia render to svg serverside and have dropped mathjax
• Andrei Alexandrescu (2/17) Sep 16 2016 Didn't know that. Did they open-source their solution? Thanks! -- Andrei
• Adam D. Ruppe (9/10) Sep 16 2016 They did, and I looked at it for my adrdox too and based my
• bachmeier (4/6) Sep 16 2016 I'm not sure it's good to compare ddoc to Wikipedia. If I want to
• Adam D. Ruppe (15/18) Sep 16 2016 It is again simple with my program: adrdox yourfile.d. It
• bachmeier (6/11) Sep 16 2016 I think that's better as a third-party tool though. MathJax and
• Andrei Alexandrescu (8/21) Sep 16 2016 Also, a bitmap image format that does not match article text in font
• Adam D. Ruppe (12/14) Sep 16 2016 That's only partially true, image links traditionally got a
• Adam D. Ruppe (3/4) Sep 16 2016 eh, speak for yourself. Even Phobos is moving away from actually
• bachmeier (5/9) Sep 16 2016 The advantage of ddoc is generating documentation from that file
• Adam D. Ruppe (11/15) Sep 16 2016 No, then it will just fallback to what it does today.
• bachmeier (13/28) Sep 16 2016 But then you introduce other problems:
• Tourist (7/11) Sep 16 2016 Bitter much? When you started Walter opined progress will soon
• Adam D. Ruppe (17/18) Sep 16 2016 It was decided some time ago that dlang.org would migrate to
• Meta (10/13) Sep 16 2016 Well, he's got at least one user. When I find the official docs
• Andrei Alexandrescu (11/33) Sep 14 2016 Generally speaking it's difficult to produce good latex documents
• Jacob Carlborg (4/8) Sep 15 2016 For reference: http://forum.dlang.org/post/nrdgl0$2p21$1@digitalmars.com
• Johan Engelen (18/27) Sep 15 2016 I think what the man is asking for is a way to write formulas in
• Manu via Digitalmars-d (3/26) Sep 15 2016 Right, thank you.
• Andrei Alexandrescu (31/51) Sep 15 2016 I see. So he's referring to LaTeX macros as an _input_ method, not as a
• Manu via Digitalmars-d (45/101) Sep 15 2016 Right, I'm not sure how I produced this confusion, but I seem to have
• Johan Engelen (44/55) Sep 15 2016 D has absolutely no notion of "databases", but I think it's fair
• Andrei Alexandrescu (7/17) Sep 15 2016 D is a language. Ddoc is a macro system. How could this simile possibly
• Johan Engelen (27/50) Sep 15 2016 Tool has absolutely nada notion of Thing. To ask "how do I do
• bachmeier (6/9) Sep 15 2016 As I commented above to Andrei, I think KaTeX is better for
• ag0aep6g (14/18) Sep 15 2016 I'm not familiar with MathJax. Looks like a client-side library. In my
• Andrei Alexandrescu (33/49) Sep 15 2016 Thanks for making that point. Does the underscore prefix work? (I'll
• Johan Engelen (3/7) Sep 15 2016 Underscore works, updating SO example.
• Johan Engelen (4/11) Sep 15 2016 I don't want to get involved in this further, as I am not going
• Andrei Alexandrescu (2/36) Sep 15 2016 Probably a wiki page would be an awesome idea. -- Andrei
Manu via Digitalmars-d <digitalmars-d puremagic.com> writes:
Can we produce formulas, or latex in ddoc? Are there any examples in
phobos I can refer to?

Sep 13 2016
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
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.

Andrei

Sep 14 2016
Manu via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 14 September 2016 at 21:36, Andrei Alexandrescu via Digitalmars-d
<digitalmars-d puremagic.com> 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.

Ah, wow, yeah I actually saw this when I googled for it before posting here.

I'm just gonna come out and say that I really don't feel like taking
the few hours it might take me to try and understand what's going on
here. I really have better things to do...
Considering I don't really know latex either, I just have to wing
that, this is like 721 lines of tedious double-indirection, with no
examples in sight ;) (yet I'm being hassled about lack of examples!)

I'm kinda feeling ddoc is fairy serious problem. Doxygen is like... a
lot better :/
I'm struggling to produce docs I'm happy with. Formatting is hard,
macros for everything really sucks!

Sep 14 2016
jmh530 <john.michael.hall gmail.com> writes:
On Wednesday, 14 September 2016 at 13:38:21 UTC, Manu wrote:
I'm just gonna come out and say that I really don't feel like
taking
the few hours it might take me to try and understand what's
going on
here. I really have better things to do...
Considering I don't really know latex either, I just have to
wing
that, this is like 721 lines of tedious double-indirection,
with no
examples in sight ;) (yet I'm being hassled about lack of
examples!)

I learned Latex by playing with LyX. You can get things looking
how you want pretty easily. When you copy some code from LyX and
paste it somewhere else, the output is the Latex code you need. I
do this somewhat frequently because the only Latex I remember is
things like subscripts and superscripts.

Sep 14 2016
Dominikus Dittes Scherkl <Dominikus.Scherkl continental-corporation.com> writes:
On Wednesday, 14 September 2016 at 13:56:26 UTC, jmh530 wrote:

I learned Latex by playing with LyX. You can get things looking
how you want pretty easily. When you copy some code from LyX
and paste it somewhere else, the output is the Latex code you
need. I do this somewhat frequently because the only Latex I
remember is things like subscripts and superscripts.

Yes, Lyx is nice and easy.
If you only want to write some heavy formulas, use Lyx.
It will put out the proper Latex, and that can be easy integrated
in DDox

Sep 15 2016
bachmeier <no spam.net> writes:
On Wednesday, 14 September 2016 at 13:38:21 UTC, Manu wrote:
On 14 September 2016 at 21:36, Andrei Alexandrescu via
Digitalmars-d <digitalmars-d puremagic.com> 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.

Ah, wow, yeah I actually saw this when I googled for it before
posting here.

I'm just gonna come out and say that I really don't feel like
taking
the few hours it might take me to try and understand what's
going on
here. I really have better things to do...
Considering I don't really know latex either, I just have to
wing
that, this is like 721 lines of tedious double-indirection,
with no
examples in sight ;) (yet I'm being hassled about lack of
examples!)

I'm kinda feeling ddoc is fairy serious problem. Doxygen is
like... a
lot better :/
I'm struggling to produce docs I'm happy with. Formatting is
hard,
macros for everything really sucks!

I agree. That's why I quickly gave up on ddoc. The macro system
needs to be better designed and documented if that's the route
you're going to choose.

That said, if all you want to do is insert equations in the
finished documentation, can't you do a simple text substitution
on the ddoc output file? I needed equations so I did that when I
started. It was a D script with only a few lines of code.

Sep 14 2016
Adam D. Ruppe <destructionator gmail.com> writes:
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.

Sep 15 2016
Manu via Digitalmars-d <digitalmars-d puremagic.com> writes:
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.

Sep 15 2016
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
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

Sep 15 2016
bachmeier <no spam.net> writes:
On Thursday, 15 September 2016 at 13:48:44 UTC, Andrei
Alexandrescu wrote:
That strikes me as an inferior solution to what's available
today, which is used at
http://erdani.com/d/DIP1000-typing-baseline.html.

But how did you do that? I think KaTeX may be a better solution
for documentation because MathJax can be slow to render. It's
basically MathJax modified for speed by Khan Academy.

https://github.com/Khan/KaTeX

Sep 15 2016
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 09/15/2016 11:13 AM, bachmeier wrote:
On Thursday, 15 September 2016 at 13:48:44 UTC, Andrei Alexandrescu wrote:
That strikes me as an inferior solution to what's available today,
which is used at http://erdani.com/d/DIP1000-typing-baseline.html.

But how did you do that?

See source at http://pasted.co/7ea68163 and Johan's example on SO.

It's imperfect: you need to define the entire DDOC macro, which is a bit
goofy because that has a bunch of other things. We need to devise a
better way in the long run.

I think KaTeX may be a better solution for
documentation because MathJax can be slow to render. It's basically
MathJax modified for speed by Khan Academy.

https://github.com/Khan/KaTeX

Even better!

Andrei

Sep 15 2016
Manu via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 15 September 2016 at 23:48, Andrei Alexandrescu via Digitalmars-d
<digitalmars-d puremagic.com> wrote:
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 guessing that's mathjax? Strangely, it renders really badly on my
system. I can barely read it.
I'd still rather use latex to produce images for my own docs.

Sep 15 2016
Johan Engelen <j j.nl> writes:
On Friday, 16 September 2016 at 02:30:37 UTC, Manu wrote:
On 15 September 2016 at 23:48, Andrei Alexandrescu:
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 guessing that's mathjax? Strangely, it renders really badly
on my
system. I can barely read it.
I'd still rather use latex to produce images for my own docs.

I believe at least the syntax for the stuff is LaTeX:
http://docs.mathjax.org/en/latest/start.html#putting-mathematics-in-a-web-page

Sep 16 2016
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/15/16 10:30 PM, Manu via Digitalmars-d wrote:
I'm guessing that's mathjax? Strangely, it renders really badly on my
system. I can barely read it.
I'd still rather use latex to produce images for my own docs.

You may want to check the options discussed at
http://tex.stackexchange.com/questions/23804/how-to-incorporate
tex-into-a-website.
-- Andrei

Sep 16 2016
Marco Leise <Marco.Leise gmx.de> writes:
Am Fri, 16 Sep 2016 12:30:37 +1000
schrieb Manu via Digitalmars-d <digitalmars-d puremagic.com>:

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 guessing that's mathjax? Strangely, it renders really badly on my
system. I can barely read it.
I'd still rather use latex to produce images for my own docs.

I don't understand any of it, but it looks really good on
Firefox. Everything is crisp and it even honors the system's
subpixel hinting setting so it even surpasses the prerendered
grayscale images from Wikipedia!

--
Marco

Sep 16 2016
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/16/16 9:17 AM, Marco Leise wrote:
Am Fri, 16 Sep 2016 12:30:37 +1000
schrieb Manu via Digitalmars-d <digitalmars-d puremagic.com>:

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 guessing that's mathjax? Strangely, it renders really badly on my
system. I can barely read it.
I'd still rather use latex to produce images for my own docs.

I don't understand any of it, but it looks really good on
Firefox. Everything is crisp and it even honors the system's
subpixel hinting setting so it even surpasses the prerendered
grayscale images from Wikipedia!

Manu, what OS/browser are you using? Could you please post a screenshot
too? Thx! -- Andrei

Sep 16 2016
bachmeier <no spam.net> writes:
On Friday, 16 September 2016 at 02:30:37 UTC, Manu wrote:

I'm guessing that's mathjax? Strangely, it renders really badly
on my
system. I can barely read it.
I'd still rather use latex to produce images for my own docs.

Normally this happens when you are not allowing the use of
MathJax fonts. It can happen on Firefox if the box "Allow pages
to choose their own fonts, instead of my selections above" is not
checked.

Sep 16 2016
Adam D. Ruppe <destructionator gmail.com> writes:
On Thursday, 15 September 2016 at 13:12:05 UTC, Manu wrote:
What does that mean? What's your process to produce this output?

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.  Sep 15 2016 Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes: On 09/15/2016 10:15 AM, Adam D. Ruppe wrote: 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

Wait, but I just showed how with vanilla ddoc you can immediately use
mathjax to do better than adrdox. No need for any pre/postprocessing or
scripting, just one line of import. Could you please respond to that? --
Andrei

Sep 15 2016
Adam D. Ruppe <destructionator gmail.com> writes:
On Thursday, 15 September 2016 at 14:40:24 UTC, Andrei
Alexandrescu wrote:
Wait, but I just showed how with vanilla ddoc you can
immediately use mathjax to do better than adrdox. No need for
any pre/postprocessing or scripting, just one line of import.

mathjax IS postprocessing via scripting. And better is extremely
dubious as it is unreliable and slow for the end user...

My method of automatic server-side image replacement gives fast,
consistent results to the reader, while being equally simple to
write for the author. It also has the advantage of working
offline, which is a major point for my docs because I like to use
them while on airplanes and such.

I'm aware of these other options. I also considered generating
MathML or SVG and decided on png because it gives the best
balance of benefits - a small image file that works everywhere
(including offline), though doesn't scale font sizes or respond
to other css instructions as well as the others, I deemed those
to be less important overall than actually displaying correctly
by default on a wide variety of devices without a massive

Sep 15 2016
tn <no email.com> writes:
On Thursday, 15 September 2016 at 17:32:16 UTC, Adam D. Ruppe
wrote:
On Thursday, 15 September 2016 at 14:40:24 UTC, Andrei
Alexandrescu wrote:
Wait, but I just showed how with vanilla ddoc you can
immediately use mathjax to do better than adrdox. No need for
any pre/postprocessing or scripting, just one line of import.

mathjax IS postprocessing via scripting. And better is
extremely dubious as it is unreliable and slow for the end
user...

Yes. I opened the link [1] by Andrei into a new tab, saw some
latex source code, wondered what was the point, closed the tab,
and remained confused. Only later did I find out that it was
supposed render it by javascript. It was way too slow.

[1] http://erdani.com/d/DIP1000-typing-baseline.html

Sep 16 2016
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/16/16 8:33 AM, tn wrote:
On Thursday, 15 September 2016 at 17:32:16 UTC, Adam D. Ruppe wrote:
On Thursday, 15 September 2016 at 14:40:24 UTC, Andrei Alexandrescu
wrote:
Wait, but I just showed how with vanilla ddoc you can immediately use
mathjax to do better than adrdox. No need for any pre/postprocessing
or scripting, just one line of import.

mathjax IS postprocessing via scripting. And better is extremely
dubious as it is unreliable and slow for the end user...

Yes. I opened the link [1] by Andrei into a new tab, saw some latex
source code, wondered what was the point, closed the tab, and remained
confused. Only later did I find out that it was supposed render it by
javascript. It was way too slow.

[1] http://erdani.com/d/DIP1000-typing-baseline.html

Yah, the whole page is exclusively rendered math, and difficult too. A
good benchmark for the rendering engine :o). -- Andrei

Sep 16 2016
bachmeier <no spam.net> writes:
On Friday, 16 September 2016 at 12:33:59 UTC, tn wrote:

Yes. I opened the link [1] by Andrei into a new tab, saw some
latex source code, wondered what was the point, closed the tab,
and remained confused. Only later did I find out that it was
supposed render it by javascript. It was way too slow.

[1] http://erdani.com/d/DIP1000-typing-baseline.html

That is why KaTeX should be used
https://khan.github.io/KaTeX/
Server side rendering is an option.

Sep 16 2016
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 09/16/2016 11:38 AM, bachmeier wrote:
On Friday, 16 September 2016 at 12:33:59 UTC, tn wrote:

Yes. I opened the link [1] by Andrei into a new tab, saw some latex
source code, wondered what was the point, closed the tab, and remained
confused. Only later did I find out that it was supposed render it by
javascript. It was way too slow.

[1] http://erdani.com/d/DIP1000-typing-baseline.html

That is why KaTeX should be used
https://khan.github.io/KaTeX/
Server side rendering is an option.

Yah, we should consider that if we get heavily into math. The fixed
installation etc. -- Andrei

Sep 16 2016
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
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

Sep 15 2016
John Colvin <john.loughran.colvin gmail.com> writes:
On Thursday, 15 September 2016 at 13:23:36 UTC, Andrei
Alexandrescu wrote:
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

Wikipedia render to svg serverside and have dropped mathjax
support.

Sep 16 2016
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/16/16 4:20 AM, John Colvin wrote:
On Thursday, 15 September 2016 at 13:23:36 UTC, Andrei Alexandrescu wrote:
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

Wikipedia render to svg serverside and have dropped mathjax support.

Didn't know that. Did they open-source their solution? Thanks! -- Andrei

Sep 16 2016
Adam D. Ruppe <destructionator gmail.com> writes:
On Friday, 16 September 2016 at 11:22:59 UTC, Andrei Alexandrescu
wrote:
Didn't know that. Did they open-source their solution? Thanks!

They did, and I looked at it for my adrdox too and based my
solution on their concepts, though I didn't use their code
(because it was too heavyweight with dependencies for my
purposes).

The Wikipedia version does a *lot* of validation (as you can
expect for a publicly editable site!) then pipes it out the latex
program, server side, to generate the image files.

Sep 16 2016
bachmeier <no spam.net> writes:
On Friday, 16 September 2016 at 08:20:34 UTC, John Colvin wrote:

Wikipedia render to svg serverside and have dropped mathjax
support.

I'm not sure it's good to compare ddoc to Wikipedia. If I want to
output documentation from a .d file, I don't want to go through a
process like that.

Sep 16 2016
Adam D. Ruppe <destructionator gmail.com> writes:
On Friday, 16 September 2016 at 15:45:36 UTC, bachmeier wrote:
I'm not sure it's good to compare ddoc to Wikipedia. If I want
to output documentation from a .d file, I don't want to go
through a process like that.

It is again simple with my program: adrdox yourfile.d. It
renders the latex to an image then embeds it in the html as a
data uri (and the original latex source as the alt attribute
which enables any fallback you can imagine).

With my thing, yes, the latex and dvipng programs need to be
installed and available for an executeShell call... but that's
not too hard, it was preinstalled on my linux anyway (and if it
fails, it falls back to outputting the source anyway soooo it
could still be used my mathjax i suppose).

It isn't really a difficult process and it is only 62 lines of
code in my doc gen source. I don't do as much validation as
Wikipedia but even if it were to, it'd just be a larger source
file, no real trouble for the end user.

This isn't really a difficult problem!

Sep 16 2016
bachmeier <no spam.net> writes:
On Friday, 16 September 2016 at 16:03:44 UTC, Adam D. Ruppe wrote:

It isn't really a difficult process and it is only 62 lines of
code in my doc gen source. I don't do as much validation as
Wikipedia but even if it were to, it'd just be a larger source
file, no real trouble for the end user.

This isn't really a difficult problem!

I think that's better as a third-party tool though. MathJax and
KaTeX require no changes to the current workflow. You have to be
able to build your documentation using DMD. If someone prefers
images, they can run their .d file through your option, and be

Sep 16 2016
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 09/16/2016 01:25 PM, bachmeier wrote:
On Friday, 16 September 2016 at 16:03:44 UTC, Adam D. Ruppe wrote:

It isn't really a difficult process and it is only 62 lines of code in
my doc gen source. I don't do as much validation as Wikipedia but even
if it were to, it'd just be a larger source file, no real trouble for
the end user.

This isn't really a difficult problem!

I think that's better as a third-party tool though. MathJax and KaTeX
require no changes to the current workflow. You have to be able to build
your documentation using DMD. If someone prefers images, they can run
their .d file through your option, and be responsible for the additional
setup.

Also, a bitmap image format that does not match article text in font
size, does not usually have proper baseline alignment for inline math,
is not as well anti-aliased as article text, can only be copied and
pasted by right-clicking on the PNG and choosing "Information about
image" and then selecting the "Associated text" to copy (in Firefox),
and does not change color when part of a link.
(https://en.wikipedia.org/wiki/Wikipedia:Rendering_math) -- Andrei

Sep 16 2016
Adam D. Ruppe <destructionator gmail.com> writes:
On Friday, 16 September 2016 at 18:30:25 UTC, Andrei Alexandrescu
wrote:
and does not change color when part of a link.

colored border (such behavior is nowadays CSS defined and still
fully possible) and there's other options too. Wikipedia might
not color it, but we could.

(https://en.wikipedia.org/wiki/Wikipedia:Rendering_math) --

But, while it is true that png output has its weaknesses,
weaknesses of the alternatives include words like "not usable",
"not supported", "not well formatted".

A png image isn't perfect for displaying this information, but it
is the best realistic option... and really easy to implement with
fallbacks to the other options.

Sep 16 2016
Adam D. Ruppe <destructionator gmail.com> writes:
On Friday, 16 September 2016 at 17:25:10 UTC, bachmeier wrote:
You have to be able to build your documentation using DMD.

eh, speak for yourself. Even Phobos is moving away from actually
using dmd's doc generator!

Sep 16 2016
bachmeier <no spam.net> writes:
On Friday, 16 September 2016 at 19:57:38 UTC, Adam D. Ruppe wrote:
On Friday, 16 September 2016 at 17:25:10 UTC, bachmeier wrote:
You have to be able to build your documentation using DMD.

eh, speak for yourself. Even Phobos is moving away from
actually using dmd's doc generator!

The advantage of ddoc is generating documentation from that file
with a single call to dmd. As soon as you add dependencies, you
either have to include it with DMD or allow the documentation to
break as soon as someone adds an equation. Neither is an option.

Sep 16 2016
Adam D. Ruppe <destructionator gmail.com> writes:
On Friday, 16 September 2016 at 20:25:33 UTC, bachmeier wrote:
The advantage of ddoc is generating documentation from that
file with a single call to dmd.

dmd could just as well call executeShell as another program.

dependencies, you either have to include it with DMD or allow
the documentation to break as soon as someone adds an equation.

No, then it will just fallback to what it does today.

That is what my program already does: if latex isn't available
(if the call to executeShell fails), it outputs the plain text,
which can still be processed by Javascript if you wish. You've
lost nothing by trying to produce the image and gained a lot of
convenience for the author and usability for the reader if it
does work. dmd can do exactly the same thing.

Y'all are letting the nonexistent perfect be the enemy of the
easily implemented good.

Sep 16 2016
bachmeier <no spam.net> writes:
On Friday, 16 September 2016 at 21:02:26 UTC, Adam D. Ruppe wrote:
On Friday, 16 September 2016 at 20:25:33 UTC, bachmeier wrote:
The advantage of ddoc is generating documentation from that
file with a single call to dmd.

dmd could just as well call executeShell as another program.

dependencies, you either have to include it with DMD or allow
the documentation to break as soon as someone adds an equation.

No, then it will just fallback to what it does today.

That is what my program already does: if latex isn't available
(if the call to executeShell fails), it outputs the plain text,
which can still be processed by Javascript if you wish. You've
lost nothing by trying to produce the image and gained a lot of
convenience for the author and usability for the reader if it
does work. dmd can do exactly the same thing.

Y'all are letting the nonexistent perfect be the enemy of the
easily implemented good.

But then you introduce other problems:

- Inconsistency in the output when you change machines or when
you build someone else's program if only one has latex installed.
- Different latex configurations will give different output.
- All machines might have latex installed but not the right
packages, or the package versions can be different.
- Not all of latex is supported by the Javascript implementations.

It would open a big can of worms to do this. I've run into so
many problems trying to collaborate with coauthors using latex
over the years. Rarely can you send a latex file to someone else
and not run into issues. This is fine for a third-party tool but
not for DMD.

Sep 16 2016
Tourist <gravatar gravatar.com> writes:
On Friday, 16 September 2016 at 19:57:38 UTC, Adam D. Ruppe wrote:
On Friday, 16 September 2016 at 17:25:10 UTC, bachmeier wrote:
You have to be able to build your documentation using DMD.

eh, speak for yourself. Even Phobos is moving away from
actually using dmd's doc generator!

Bitter much? When you started Walter opined progress will soon
stall and you will have an incomplete tool with no users to
maintain. That is what happened. I appreciate your contributions
to D and your overall decency as a human being. It makes it all
the more surprising when you lose it all to stridently promote
your tool and demean ddoc and ddox.

Sep 16 2016
Adam D. Ruppe <destructionator gmail.com> writes:
On Friday, 16 September 2016 at 20:46:55 UTC, Tourist wrote:
Bitter much?

It was decided some time ago that dlang.org would migrate to
ddox. There was even a push by Andrei recently to hammer out some
more of the ddox bugs to keep these plans on track, and he
reported another just today.

Web traffic analysis also recently showed the ddox pages are
significantly more popular than the ddoc pages.
https://github.com/dlang/dlang.org/pull/1363#issuecomment-241770552

Even Walter this week considered changing the syntax and has said
he changed his mind on Markdown!
http://forum.dlang.org/post/nrh0bi$1elq$2 digitalmars.com

And finally, the Phobos doc generation process has used more than
just dmd for a very long time anyway... in fact, it even already
lists latex as an optional dependency!

https://github.com/dlang/dlang.org/blob/master/CONTRIBUTING.md

So it is simply objective fact that we don't have to be able to
build the documentation using dmd, especially not dmd alone.

Sep 16 2016
Meta <jared771 gmail.com> writes:
On Friday, 16 September 2016 at 20:46:55 UTC, Tourist wrote:
Bitter much? When you started Walter opined progress will soon
stall and you will have an incomplete tool with no users to
maintain. That is what happened.

Well, he's got at least one user. When I find the official docs
too cluttered or difficult to understand due to a huge symbol
dump on the page (such as with some of the docs in
std.experimental.logging and elsewhere), I go to Adam's
documentation which is usually much easier to read and
understand. He can also respond to bug reports much faster as
it's a one-person project and all it takes is an email. I found a
bug in symbol searching awhile back and he had it fixed within an
hour or so.

Sep 16 2016
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 09/14/2016 09:38 AM, Manu via Digitalmars-d wrote:
On 14 September 2016 at 21:36, Andrei Alexandrescu via Digitalmars-d
<digitalmars-d puremagic.com> 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.

Ah, wow, yeah I actually saw this when I googled for it before posting here.

I'm just gonna come out and say that I really don't feel like taking
the few hours it might take me to try and understand what's going on
here. I really have better things to do...
Considering I don't really know latex either, I just have to wing
that, this is like 721 lines of tedious double-indirection, with no
examples in sight ;) (yet I'm being hassled about lack of examples!)

Generally speaking it's difficult to produce good latex documents
without knowing latex, so it may be the case a latex crash course is
needed or the task is ill-defined.

That said, the stuff I published at
http://erdani.com/d/DIP1000-grammar.html and
http://erdani.com/d/DIP1000-typing-baseline.html use MathJAX, you may
want to take a look. Truth be told that's generated code (using a much
smaller ddoc source).

I'm kinda feeling ddoc is fairy serious problem. Doxygen is like... a
lot better :/
I'm struggling to produce docs I'm happy with. Formatting is hard,
macros for everything really sucks!

Why?

Andrei

Sep 14 2016
Jacob Carlborg <doob me.com> writes:
On 2016-09-14 15:38, Manu via Digitalmars-d wrote:

I'm kinda feeling ddoc is fairy serious problem. Doxygen is like... a
lot better :/
I'm struggling to produce docs I'm happy with. Formatting is hard,
macros for everything really sucks!

For reference: http://forum.dlang.org/post/nrdgl0$2p21$1 digitalmars.com

--
/Jacob Carlborg

Sep 15 2016
Johan Engelen <j j.nl> writes:
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.

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

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

On Wednesday, 14 September 2016 at 13:38:21 UTC, Manu wrote:
I'm kinda feeling ddoc is fairy serious problem. Doxygen is
like... a lot better :/

Definitely :/

-Johan

Sep 15 2016
Manu via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 15 September 2016 at 19:50, Johan Engelen via Digitalmars-d
<digitalmars-d puremagic.com> 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.

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

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

Right, thank you.

Sep 15 2016
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
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  Sep 15 2016 Manu via Digitalmars-d <digitalmars-d puremagic.com> writes: 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).

Sep 15 2016
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
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  Sep 15 2016 Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes: 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  Sep 15 2016 Johan Engelen <j j.nl> writes: 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>
* <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.

:)

Sep 15 2016
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 09/15/2016 10:37 AM, Johan Engelen wrote:
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".

D is a language. Ddoc is a macro system. How could this simile possibly
convey any information?

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.

No, sorry Johan this is a hopeless misunderstanding. Ddoc does not
render absolutely anything. All it can do is output UTF text! We need to
clear this up before continuing.

Andrei

Sep 15 2016
Johan Engelen <j j.nl> writes:
On Thursday, 15 September 2016 at 14:42:37 UTC, Andrei
Alexandrescu wrote:
On 09/15/2016 10:37 AM, Johan Engelen wrote:
On Thursday, 15 September 2016 at 11:39:13 UTC, Andrei
Alexandrescu wrote:
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
"how do I retrieve data from a database using D".

D is a language. Ddoc is a macro system. How could this simile
possibly convey any information?

Tool has absolutely nada notion of Thing. To ask "how do I do
Thing with Tool", can still be an OK question (listener willing)
to which there is a simple answer that you yourself have given
here (thanks!!). Let's stop here? ;)
Btw, Ddoc is perhaps a little more than a macro system, and
that's why using parameter names in equations is broken.
Parameter names are replaced by (wait for it) a macro, so
disabling that macro "fixes" the issue. See the stackoverflow
example.
http://stackoverflow.com/a/39514239/3215806

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.

No, sorry Johan this is a hopeless misunderstanding. Ddoc does
not render absolutely anything. All it can do is output UTF
text! We need to clear this up before continuing.

I know that DDoc (currently) is just outputting a text file. I
wrote "end up with...".
Please zoom out a little, read between the lines; I think most
here write messages  without spelling out everything in exact
mathematical detail. ;)
So indeed, the DDoc system does provide a simple way to end up
with nice-looking equations: "import" MathJax, and just write
$$...$$. Excellent.

- Is there a way to "import" MathJax without having to redefine
the DDOC macro?(seems a little brittle)

- Perhaps we can "standardize" the MathJax thing for Phobos docs?
Would be nice for Manu's color lib and for Mir too. (where are
the Mir guys anyway in this discussion? ;)

- Also, how about that parameter name problem? Any good fix for
that?

Sep 15 2016
bachmeier <no spam.net> writes:
On Thursday, 15 September 2016 at 15:43:39 UTC, Johan Engelen
wrote:

- Perhaps we can "standardize" the MathJax thing for Phobos
docs? Would be nice for Manu's color lib and for Mir too.
(where are the Mir guys anyway in this discussion? ;)

As I commented above to Andrei, I think KaTeX is better for
documentation, because MathJax can be slow. KaTeX is basically
MathJax that has been modified to be faster.

https://github.com/Khan/KaTeX

Sep 15 2016
ag0aep6g <anonymous example.com> writes:
On 09/15/2016 05:43 PM, Johan Engelen wrote:
- Perhaps we can "standardize" the MathJax thing for Phobos docs? Would
be nice for Manu's color lib and for Mir too. (where are the Mir guys
anyway in this discussion? ;)

I'm not familiar with MathJax. Looks like a client-side library. In my
opinion that's not good enough. The work should be done during the build
process, not in the browser. But maybe MathJax can be used that way?

- Also, how about that parameter name problem? Any good fix for that?

Unless we're willing to get rid of auto-highlighting everywhere, the
usual underscore prefixing will probably have to do.

Example:
----
/**
p <- highlighted
_p <- not highlighted, no underscore in output
*/
void f(int p) {}
----

Sep 15 2016
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 09/15/2016 11:43 AM, Johan Engelen wrote:
On Thursday, 15 September 2016 at 14:42:37 UTC, Andrei Alexandrescu wrote:
On 09/15/2016 10:37 AM, Johan Engelen wrote:

Btw, Ddoc is perhaps a little more than a macro system, and that's why
using parameter names in equations is broken. Parameter names are
replaced by (wait for it) a macro, so disabling that macro "fixes" the
issue. See the stackoverflow example.
http://stackoverflow.com/a/39514239/3215806

Thanks for making that point. Does the underscore prefix work? (I'll
note that DDOC_PARAM is one of those things in the vein that many clamor
for - do things automatically without a macro in sight...)

So indeed, the DDoc system does provide a simple way to end up with
nice-looking equations: "import" MathJax, and just write $$...$$.
Excellent.

- Is there a way to "import" MathJax without having to redefine the DDOC
macro?(seems a little brittle)

Yah, I think it's suboptimal to have to redefine DDOC (which in serious
apps has a bunch of stuff) just for a few pages that need certain stuff
in the html head. (This is a similar issue with various entities adding

What an application can do is this:

CUSTOM_DDOC =
<!DOCTYPE html>
<html lang="en-US">
$0 <title>$(TITLE)</title>
<body><h1>$(TITLE)</h1>$(BODY)</body>
</html>
DDOC = $(CUSTOM_DDOC) Then, the pages that want mathjax go: Macros: DDOC =$(CUSTOM_DDOC <script type="text/javascript" async
src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-MML-AM_CHTML"></script>)

In fact I think it would be a great idea to do this right now for Phobos
and mathspecial.

Another solution is to define and use some macro a la DDOC_EXTRA_HEADER
(and probably DDOC_EXTRA_FOOTER) but probably the one above is simpler
and better.

- Perhaps we can "standardize" the MathJax thing for Phobos docs? Would
be nice for Manu's color lib and for Mir too. (where are the Mir guys
anyway in this discussion? ;)

Johan, do you think I could impose on you to try your hand? The solution
would redefine DDOC as above and involve dlang.org and (then)
std.mathspecial.

- Also, how about that parameter name problem? Any good fix for that?

Let's see how the underscore does.

Andrei

Sep 15 2016
Johan Engelen <j j.nl> writes:
On Thursday, 15 September 2016 at 16:35:53 UTC, Andrei
Alexandrescu wrote:
- Also, how about that parameter name problem? Any good fix
for that?

Let's see how the underscore does.

Underscore works, updating SO example.

Sep 15 2016
Johan Engelen <j j.nl> writes:
On Thursday, 15 September 2016 at 16:35:53 UTC, Andrei
Alexandrescu wrote:
On 09/15/2016 11:43 AM, Johan Engelen wrote:
- Perhaps we can "standardize" the MathJax thing for Phobos
docs?

Johan, do you think I could impose on you to try your hand? The
solution would redefine DDOC as above and involve dlang.org and
(then) std.mathspecial.

I don't want to get involved in this further, as I am not going
to be the one using it.

Sep 15 2016
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 09/15/2016 10:37 AM, Johan Engelen wrote:
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">
* <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.

:)

Probably a wiki page would be an awesome idea. -- Andrei

Sep 15 2016
Johan Engelen <j j.nl> writes:
On Thursday, 15 September 2016 at 14:43:56 UTC, Andrei
Alexandrescu wrote:
On 09/15/2016 10:37 AM, Johan Engelen wrote:
this as
:)

Probably a wiki page would be an awesome idea. -- Andrei

We need more stackoverflow stuff. The voting system is awesome to
get an answer to straightforward questions in a split second.

https://stackoverflow.com/questions/39514027/how-to-show-math-equations-with-ddoc

Sep 15 2016
Jonathan M Davis via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Thursday, September 15, 2016 10:43:56 Andrei Alexandrescu via Digitalmars-d
wrote:
Probably a wiki page would be an awesome idea. -- Andrei

Well, for better or worse, he asked it on SO:

http://stackoverflow.com/questions/39514027/how-to-show-math-equations-with-ddoc

Sep 15 2016