Re: ddoc latex/formulas?
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.
Re: ddoc latex/formulas?
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.
Re: ddoc latex/formulas?
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.
Re: ddoc latex/formulas?
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.
Re: ddoc latex/formulas?
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.
Re: ddoc latex/formulas?
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.
Re: ddoc latex/formulas?
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.
Re: ddoc latex/formulas?
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!
Re: ddoc latex/formulas?
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
Re: ddoc latex/formulas?
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.
Re: ddoc latex/formulas?
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 s 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!
Re: ddoc latex/formulas?
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
Re: ddoc latex/formulas?
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.
Re: ddoc latex/formulas?
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.
Re: ddoc latex/formulas?
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.
Re: ddoc latex/formulas?
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
Re: ddoc latex/formulas?
On 9/16/16 9:17 AM, Marco Leise wrote: Am Fri, 16 Sep 2016 12:30:37 +1000 schrieb Manu via Digitalmars-d : 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
Re: ddoc latex/formulas?
Am Fri, 16 Sep 2016 12:30:37 +1000 schrieb Manu via Digitalmars-d : > > 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
Re: ddoc latex/formulas?
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
Re: ddoc latex/formulas?
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.
Re: ddoc latex/formulas?
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
Re: ddoc latex/formulas?
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
Re: ddoc latex/formulas?
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
Re: ddoc latex/formulas?
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.
Re: ddoc latex/formulas?
On 15 September 2016 at 23:48, Andrei Alexandrescu via Digitalmars-d 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 >> 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.
Re: ddoc latex/formulas?
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.
Re: ddoc latex/formulas?
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.
Re: ddoc latex/formulas?
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.
Re: ddoc latex/formulas?
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 = $0 $(TITLE) $(TITLE)$(BODY) DDOC = $(CUSTOM_DDOC) Then, the pages that want mathjax go: Macros: DDOC = $(CUSTOM_DDOC src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-MML-AM_CHTML";>) 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
Re: ddoc latex/formulas?
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) {}
Re: ddoc latex/formulas?
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
Re: ddoc latex/formulas?
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
Re: ddoc latex/formulas?
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?
Re: ddoc latex/formulas?
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
Re: ddoc latex/formulas?
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
Re: ddoc latex/formulas?
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
Re: ddoc latex/formulas?
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 =
*
*
*
* https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-MML-AM_CHTML";>
*
* $(TITLE)
*
* $(TITLE)$(BODY)
*
*/
/**
* \[
* \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
Re: ddoc latex/formulas?
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
Re: ddoc latex/formulas?
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
Re: ddoc latex/formulas?
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 . 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 = * * * * src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-MML-AM_CHTML";>* * $(TITLE) * * $(TITLE)$(BODY) * */ /** * \[ * \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? :)
Re: ddoc latex/formulas?
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.
Re: ddoc latex/formulas?
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
Re: ddoc latex/formulas?
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 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
Re: ddoc latex/formulas?
On 09/15/2016 08:42 AM, Manu via Digitalmars-d wrote: On 15 September 2016 at 21:39, Andrei Alexandrescu via Digitalmars-d 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
Re: ddoc latex/formulas?
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
Re: ddoc latex/formulas?
On 15 September 2016 at 22:40, Adam D. Ruppe via Digitalmars-d 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.
Re: ddoc latex/formulas?
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.
Re: ddoc latex/formulas?
On 15 September 2016 at 21:39, Andrei Alexandrescu via Digitalmars-d
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 .
>
>
> 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, whatev
Re: ddoc latex/formulas?
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 .
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
Re: ddoc latex/formulas?
On 15 September 2016 at 19:50, Johan Engelen via Digitalmars-d 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 . Right, thank you.
Re: ddoc latex/formulas?
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
Re: ddoc latex/formulas?
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 . 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
Re: ddoc latex/formulas?
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
Re: ddoc latex/formulas?
On 09/14/2016 09:38 AM, Manu via Digitalmars-d wrote: On 14 September 2016 at 21:36, Andrei Alexandrescu via Digitalmars-d 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
Re: ddoc latex/formulas?
On Wednesday, 14 September 2016 at 13:38:21 UTC, Manu wrote: On 14 September 2016 at 21:36, Andrei Alexandrescu via Digitalmars-d 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.
Re: ddoc latex/formulas?
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.
Re: ddoc latex/formulas?
On 14 September 2016 at 21:36, Andrei Alexandrescu via Digitalmars-d 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!
Re: ddoc latex/formulas?
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
