It's possible to use latex render sites [1], then shrink link by tiny URL [2]. Then paste like usual image. [1] http://www.codecogs.com/latex/eqneditor.php [2] http://tinyurl.com -- Alexander On Jan 7, 2014 2:20 AM, "Mateusz Kowalczyk" wrote:

On 06/01/14 18:49, Peter Caspers wrote:

...

Hi,

I am still very new to Haskell, trying to start my very first project. For its documentation I want to use Haddock and suitable comments in the source code.

I notice that (e.g. different from doxygen) there is no direct way of writing formulas, say in TeX style. Looking into some projects on Hackage, formulas there seem to be written in "pseudo-code" more or less like TeX but not following any strict standard. As far as I can see.

That's right, there's no direct way to embed maths in Haddock. It has been a somewhat requested feature for Haddock over summer when I did work on it but it didn't make it in.

...

What would be your recommendations concerning this ? Is there some guideline on how to include formulas ? I understand that there is "literal programming" where you can e.g. write a TeX article with embedded code blocks that can be extracted for the compiler. However, I do not want to follow this path, also the result is a bit different from what is produced in the "traditional" approach, isn't it.

If you want manually-written LaTeX, this is probably the only way at the moment. If all you want is some LaTeX snippets (maths), your best bet is to probably write those separately, make images out of them and then embed them into your documentation. There's currently no way for Haddock to do this for you. We do however have a LaTeX back-end so it's not like it's impossible to generate but it'd require some work that has not yet been put in.

...

Thanks a lot Peter _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe

-- Mateusz K. _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe

I would really love to use MathJax in the haddock HTML backend. Is there any way (however hacky) that I could do that? On Monday, January 6, 2014, Joachim Breitner wrote:

Hi,

it should also be possible to render Formulas to SVG, and embed the SVG-File using a data-URL, and get a vector rendering of your formular.... similar to the image in

http://hackage.haskell.org/package/circle-packing-0.1.0.3/docs/Optimisation-...

But probably that will hit size bounds very soon.

http://hackage.haskell.org/package/diagrams-haddock works similarly, and also explains how to ship the SVG files separately, to not hit size bounds.

I guess a tool similar to that, latex-haddock, would be feasible and useful.

Greetings, Joachim

Am Dienstag, den 07.01.2014, 03:44 +0400 schrieb Alexander V Vershilov:

...

It's possible to use latex render sites [1], then shrink link by tiny URL [2]. Then paste like usual image.

[1] http://www.codecogs.com/latex/eqneditor.php [2] http://tinyurl.com

-- Alexander

On Jan 7, 2014 2:20 AM, "Mateusz Kowalczyk" wrote: On 06/01/14 18:49, Peter Caspers wrote: > Hi, > > I am still very new to Haskell, trying to start my very first project. > For its documentation I want to use Haddock and suitable comments in > the source code. > > I notice that (e.g. different from doxygen) there is no direct way of > writing formulas, say in TeX style. Looking into some projects on > Hackage, formulas there > seem to be written in "pseudo-code" more or less like TeX but not > following any strict standard. As far as I can see.

That's right, there's no direct way to embed maths in Haddock. It has been a somewhat requested feature for Haddock over summer when I did work on it but it didn't make it in.

> What would be your recommendations concerning this ? Is there some > guideline on how to include formulas ? I understand that there is > "literal programming" > where you can e.g. write a TeX article with embedded code blocks that > can be extracted for the compiler. However, I do not want to follow > this path, also the > result is a bit different from what is produced in the "traditional" > approach, isn't it.

If you want manually-written LaTeX, this is probably the only way at the moment. If all you want is some LaTeX snippets (maths), your best bet is to probably write those separately, make images out of them and then embed them into your documentation. There's currently no way for Haddock to do this for you. We do however have a LaTeX back-end so it's not like it's impossible to generate but it'd require some work that has not yet been put in.

> Thanks a lot > Peter > _______________________________________________ > Haskell-Cafe mailing list > Haskell-Cafe@haskell.org > http://www.haskell.org/mailman/listinfo/haskell-cafe >

-- Mateusz K. _______________________________________________ Haskell-Cafe mailing list Joachim Breitner e-Mail: mail@joachim-breitner.de javascript:; Homepage: http://www.joachim-breitner.de Jabber-ID: nomeata@joachim-breitner.de javascript:;

Thanks. I guess the best way for me is just writing the formulas as TeX - code fragments, then it should be easy to adapt to any potential Haddock extensions to come in the future. At the same time this notation is readable enough even as plain text in my opinion. Peter On 7 January 2014 03:52, Mateusz Kowalczyk wrote:

On 07/01/14 01:42, Carter Schonwald wrote:

...

I would really love to use MathJax in the haddock HTML backend. Is there any way (however hacky) that I could do that?

I looked up how MathJax is used and as far as I can tell, it's just the case of putting the MathJax JavaScript header into the file, right? We already use JavaScript on the Haddock-generated HTML pages, for example the synopsis box.

While I prefer JavaScript-free web I think that for viewing on Hackage, it'd be possible to just stick the header into the generated files and be done with it. Here are some caveats:

* You suddenly allow for part of documentation to be rendered by someone else, over the Internet. The problem is that documentation suddenly becomes worse for everyone browsing without JavaScript or browsing locally, without an Internet connection. Embedding images avoids both of these problems.

* With the wealth of characters you're likely to use while writing LaTeX, it would clash with existing Haddock syntax sooner or later so this would have to be handled. I spent my summer working on Haddock parser and the new version allows you to escape things properly but the currently used one is very limited in that aspect. You'd probably end up having to introduce some kind of ‘verbatim’ block to Haddock's syntax which tells it to just take things at face value. It'd not be too hard with the new parser. We're having problems getting the new parser merged however (problems validating GHC to check that we haven't broken everything ever).

* This touches on frequently overlooked problem: Haddock targets more than just the HTML back-end. We also have the LaTeX back-end and the Hoogle back-end. This is why we don't allow things like verbatim HTML in the markup, it doesn't make sense for anything but HTML. Admittedly, LaTeX back-end could just generate the maths itself but we then suddenly have to change the ‘verbatim’ block to the ‘LaTeX’ block. It's also unclear how Hoogle back-end would deal with this. Even if we add the ‘LaTeX structure‘ to Haddock, I'm afraid that it might end up with people just writing LaTeX for their documentation which is useless for anyone not using that back-end.

So, yes, it'd be possible but it'd be very hacky. Not from the code aspect of things, but from the design aspect of it.

Perhaps it'd be possible to have pieces of documentation targeting specific back-ends, kind of like internal Haddock pragma if you will, which would allow the user to write differently looking docs for each back-end. At this point however, it becomes clunky to use, horrible to maintain and simply including images in your docs is the easier way out, especially because you're no longer limited by what Haddock can do. I recommend against this kind of thought and I expect that most people that have worked on Haddock would agree.

In conclusion, if you want maths in your comments, use images.

-- Mateusz K. _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe

On Tue, Jan 7, 2014 at 7:18 AM, Antonio Nikishaev wrote:

Mateusz Kowalczyk writes:

...

* You suddenly allow for part of documentation to be rendered by someone else, over the Internet. The problem is that documentation suddenly becomes worse for everyone browsing without JavaScript or browsing locally, without an Internet connection. Embedding images avoids both of these problems.

No. It's rendered in the browser.

For me as a programmer writing documentation, your random browser and its random collection of javascript and css bugs --- or potentially lack of one/both --- is "someone else" that I must potentially deal with. -- brandon s allbery kf8nh sine nomine associates allbery.b@gmail.com ballbery@sinenomine.net unix, openafs, kerberos, infrastructure, xmonad http://sinenomine.net

In the case of MathJax, the fall back is you just get some inline latex. On Tuesday, January 7, 2014, Mateusz Kowalczyk wrote:

...

Mateusz Kowalczyk javascript:;> writes:

...

On 07/01/14 01:42, Carter Schonwald wrote:

...

I would really love to use MathJax in the haddock HTML backend. Is

On 07/01/14 12:18, Antonio Nikishaev wrote: there

...

...

...

any way (however hacky) that I could do that?

I looked up how MathJax is used and as far as I can tell, it's just the case of putting the MathJax JavaScript header into the file, right? We already use JavaScript on the Haddock-generated HTML pages, for example the synopsis box.

While I prefer JavaScript-free web I think that for viewing on Hackage, it'd be possible to just stick the header into the generated files and be done with it. Here are some caveats:

* You suddenly allow for part of documentation to be rendered by someone else, over the Internet. The problem is that documentation suddenly becomes worse for everyone browsing without JavaScript or browsing locally, without an Internet connection. Embedding images avoids both of these problems.

No. It's rendered in the browser.

It still requires an Internet connection, does it not? Many people prefer to browse without JavaScript anyway (myself included) and if the documentation suddenly requires JavaScript to view properly, this is a problem.

-- Mateusz K. _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org javascript:; http://www.haskell.org/mailman/listinfo/haskell-cafe

On 01/08/2014 12:23 PM, Ben Foppa wrote:

I tend to opt for writing plaintext LaTeX, and if the reader wants it to be pretty, they can use TeX the World (although it looks like this is now unmaintained and only viable in chrome).

The Sage project[1] has to solve a similar problem with its python reference documentation for various mathy things. These days MathJax is used, but in my opinion the previous solution was better. While the HTML documentation was being generated from RST, various magics were employed to convert the embedded formulas to PNGs which were then inserted directly into the markup. Haddock could probably be convinced to do the same. The downside to images is that they don't scale, but they do have the alt attribute as a plain-text fallback. The problem with MathJax is that it takes forever to load and slows the browser to a crawl -- especially annoying when you know what you're looking for and can't scroll to it because the document keeps jumping around as formulas load for 30 seconds. Images load instantly and look good enough. [1] http://sagemath.org/

* Mateusz Kowalczyk [2014-01-07 02:52:12+0000]

* This touches on frequently overlooked problem: Haddock targets more than just the HTML back-end. We also have the LaTeX back-end and the Hoogle back-end. This is why we don't allow things like verbatim HTML in the markup, it doesn't make sense for anything but HTML. Admittedly, LaTeX back-end could just generate the maths itself but we then suddenly have to change the ‘verbatim’ block to the ‘LaTeX’ block. It's also unclear how Hoogle back-end would deal with this. Even if we add the ‘LaTeX structure‘ to Haddock, I'm afraid that it might end up with people just writing LaTeX for their documentation which is useless for anyone not using that back-end.

I see no reason why haddock should have a hoogle backend, as opposed to hoogle using the GHC API directly. It's just a hack that exists for historical reasons. Other than that, HTML is the only backend really in use at the moment, I believe. Roman

Interesting, I didn't know that. So the libraries part of the Haskell Report simply documents the status quo? * malcolm.wallace [2014-01-07 13:24:38+0000]

I believe the LaTeX backend for Haddock is used to generate the libraries part of the Haskell Report. Regards, Malcolm

On 07 Jan, 2014,at 01:10 PM, Roman Cheplyaka wrote:

* Mateusz Kowalczyk [2014-01-07 02:52:12+0000] * This touches on frequently overlooked problem: Haddock targets more than just the HTML back-end. We also have the LaTeX back-end and the Hoogle back-end. This is why we don't allow things like verbatim HTML in the markup, it doesn't make sense for anything but HTML. Admittedly, LaTeX back-end could just generate the maths itself but we then suddenly have to change the ‘verbatim’ block to the ‘LaTeX’ block. It's also unclear how Hoogle back-end would deal with this. Even if we add the ‘LaTeX structure‘ to Haddock, I'm afraid that it might end up with people just writing LaTeX for their documentation which is useless for anyone not using that back-end.

I see no reason why haddock should have a hoogle backend, as opposed to hoogle using the GHC API directly. It's just a hack that exists for historical reasons.

Other than that, HTML is the only backend really in use at the moment, I believe.

Roman _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe

_______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe

+1 for MathJax. It was my first thought when the question came up. On Mon, Jan 6, 2014 at 5:42 PM, Carter Schonwald

wrote:

I would really love to use MathJax in the haddock HTML backend. Is there any way (however hacky) that I could do that?

On Monday, January 6, 2014, Joachim Breitner wrote:

...

Hi,

it should also be possible to render Formulas to SVG, and embed the SVG-File using a data-URL, and get a vector rendering of your formular.... similar to the image in

http://hackage.haskell.org/package/circle-packing-0.1.0.3/docs/Optimisation-...

But probably that will hit size bounds very soon.

http://hackage.haskell.org/package/diagrams-haddock works similarly, and also explains how to ship the SVG files separately, to not hit size bounds.

I guess a tool similar to that, latex-haddock, would be feasible and useful.

Greetings, Joachim

Am Dienstag, den 07.01.2014, 03:44 +0400 schrieb Alexander V Vershilov:

...

It's possible to use latex render sites [1], then shrink link by tiny URL [2]. Then paste like usual image.

[1] http://www.codecogs.com/latex/eqneditor.php [2] http://tinyurl.com

-- Alexander

On Jan 7, 2014 2:20 AM, "Mateusz Kowalczyk" wrote: On 06/01/14 18:49, Peter Caspers wrote: > Hi, > > I am still very new to Haskell, trying to start my very first project. > For its documentation I want to use Haddock and suitable comments in > the source code. > > I notice that (e.g. different from doxygen) there is no direct way of > writing formulas, say in TeX style. Looking into some projects on > Hackage, formulas there > seem to be written in "pseudo-code" more or less like TeX but not > following any strict standard. As far as I can see.

That's right, there's no direct way to embed maths in Haddock. It has been a somewhat requested feature for Haddock over summer when I did work on it but it didn't make it in.

> What would be your recommendations concerning this ? Is there some > guideline on how to include formulas ? I understand that there is > "literal programming" > where you can e.g. write a TeX article with embedded code blocks that > can be extracted for the compiler. However, I do not want to follow > this path, also the > result is a bit different from what is produced in the "traditional" > approach, isn't it.

If you want manually-written LaTeX, this is probably the only way at the moment. If all you want is some LaTeX snippets (maths), your best bet is to probably write those separately, make images out of them and then embed them into your documentation. There's currently no way for Haddock to do this for you. We do however have a LaTeX back-end so it's not like it's impossible to generate but it'd require some work that has not yet been put in.

> Thanks a lot > Peter > _______________________________________________ > Haskell-Cafe mailing list > Haskell-Cafe@haskell.org > http://www.haskell.org/mailman/listinfo/haskell-cafe >

-- Mateusz K. _______________________________________________ Haskell-Cafe mailing list Joachim Breitner e-Mail: mail@joachim-breitner.de Homepage: http://www.joachim-breitner.de Jabber-ID: nomeata@joachim-breitner.de

_______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe

I seem to recall that certain browsers have dropped mathml support. Recent Firefox I think? I'm away from my computer so I can't look it up right now On Sunday, January 12, 2014, Daniil Frumin wrote:

What do you folks think of MathML?

On Mon, Jan 6, 2014 at 10:49 PM, Peter Caspers javascript:;> wrote:

...

Hi,

I am still very new to Haskell, trying to start my very first project. For its documentation I want to use Haddock and suitable comments in the source code.

I notice that (e.g. different from doxygen) there is no direct way of writing formulas, say in TeX style. Looking into some projects on Hackage, formulas there seem to be written in "pseudo-code" more or less like TeX but not following any strict standard. As far as I can see.

What would be your recommendations concerning this ? Is there some guideline on how to include formulas ? I understand that there is "literal programming" where you can e.g. write a TeX article with embedded code blocks that can be extracted for the compiler. However, I do not want to follow this path, also the result is a bit different from what is produced in the "traditional" approach, isn't it.

Thanks a lot Peter _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org javascript:; http://www.haskell.org/mailman/listinfo/haskell-cafe

-- Sincerely yours, -- Daniil _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org javascript:; http://www.haskell.org/mailman/listinfo/haskell-cafe

On Mon, 2014-01-13 at 01:27 +0400, Daniil Frumin wrote:

What do you folks think of MathML?

Well, the de facto way to render MathML *is* with Mathjax. Rendering Latex is a side thing (obviously significant for adoption, but still a sideline) for them. So either way, whether it's inline Latex or inline MathML, the nicest outcome for rendering math in a browser is Mathjax. AfC Sydney