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