www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - ddoc latex/formulas?

reply 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
parent reply 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
next sibling parent reply 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
next sibling parent reply 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
parent 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
prev sibling next sibling parent reply 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
parent reply 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
next sibling parent reply 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
next sibling parent reply 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
next sibling parent reply 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
parent 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
prev sibling parent reply 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
next sibling parent 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
prev sibling next sibling parent 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
prev sibling next sibling parent reply 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
parent 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
prev sibling parent 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
prev sibling parent reply 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?


./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.
Sep 15 2016
parent reply 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
 a dead end.


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
parent reply 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 
download.
Sep 15 2016
parent reply 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
next sibling parent 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
prev sibling parent reply 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
parent 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 
costs are larger than with mathjax, what with downloading and 
installation etc. -- Andrei
Sep 16 2016
prev sibling parent reply 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
parent reply 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
next sibling parent reply 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
parent 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
prev sibling parent reply 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
parent reply 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
parent reply 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 
responsible for the additional setup.
Sep 16 2016
next sibling parent reply 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
parent 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.


That's only partially true, image links traditionally got a 
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
prev sibling parent reply 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
next sibling parent reply 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
parent reply 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
parent 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
prev sibling parent reply 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
next sibling parent 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
prev sibling parent 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
prev sibling next sibling parent 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
prev sibling parent 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
prev sibling parent reply 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
next sibling parent 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
prev sibling parent reply 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
next sibling parent reply 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
parent reply 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
parent 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
prev sibling parent reply 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>
* </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?
:)
Sep 15 2016
next sibling parent reply 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
parent reply 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:

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


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
next sibling parent 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
prev sibling next sibling parent 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
prev sibling parent reply 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 
headers to http requests.)

What an application can do is this:

CUSTOM_DDOC =
<!DOCTYPE html>
<html lang="en-US">
<head>
$0
<title>$(TITLE)</title>
</head>
<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
next sibling parent 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
prev sibling parent 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
prev sibling parent reply 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">
 * <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?
 :)


Probably a wiki page would be an awesome idea. -- Andrei
Sep 15 2016
next sibling parent 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:

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


 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
prev sibling parent 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