On 4/27/13 2:12 PM, Luc Maisonobe wrote: > [switching to the dev list for the discussion] > > Le 26/04/2013 00:04, Gilles (JIRA) a écrit : >> [ >> https://issues.apache.org/jira/browse/MATH-968?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13642278#comment-13642278 >> ] >> >> Gilles commented on MATH-968: >> ----------------------------- >> >> I proposed to test something similar some time ago: >> http://users.informatik.uni-halle.de/~grau/LaTeXlet/ >> >> But there has been significant reluctance about licensing, dependencies, and >> plainly having LaTeX code inside the Javadoc. >> >> IMHO, there are two options: >> # LaTeX-based extension to create beautiful (when generated!) comments >> # Basic Javadoc, no fancy formulae (especially _not_ using plain HTML) > For simple formulas, like greek letters, using plain UTF-8 in javadoc > seems OK to me. We could even do a global search and replace easily to > change the most frequent html entities in our current code (pi, alpha, > and perhaps times, sum, int and radic...) into the appropriate unicode > character. It is even possible to use numerical superscripts for writing > polynomials. > > However, I agree with Gilles we should not go too far this way and don't > try to tranlitterates everything. I don't if if the following example > will show up in the mail, but I wrote it in plain UTF-8: > > ∫𝛼ₘ²+𝛽ₙ⁶ > > In case it does not show up, it is an integral sign, alpha, subscript m, > superscript 2, plus sign, beta, subscript n, superscript 6. Writing > these 8 characters was a pain and a lot of copy/pasting from reference > character tables. On my computer, it does not even looks very good > because mising subscript and superscript does not work well as they are > separate characters and are not aligned vertically. Another problem with > this approach is that we will hit the limits pretty quickly. As an > example, using a greek letter as an exponent like is done in the patch > proposed for MATH-968 is not possible in unicode. There are only a few > characters available for superscript or subscript. > > So using unicode and only unicode seems to be a pain and not sufficient. > > On the other hand, going to the other extreme and getting a dedicated > doclet that implies installing LaTeX to generate javadocs is really to > much for users. > > So I think the intermediate solution using mathjax with LaTeX syntax as > suggested by Thomas would be good. In fact, it could also be used in the > user guide as we have already discussed about it. One message from > Sébastien in particular <http://markmail.org/message/ljvfldrzvxsmh2ak> > showed we could add support for mathjax in our user guide very easily. > Even more since we switched to svnpubsub and changing the site is mainly > doing a commit. > > Note that our documentation is expected to be viewed either generated as > a web site inside a browser or read in an editor while working on the > code itself. MathJax takes care of the former case beautifully, and > using LaTeX syntax (instead of mathml for example) would be fine for the > second case. LaTeX formulas remain understandable when read without any > tools (even on a paper copy of the code), as long as we restrict > ourselves to not writing complete mathematical articles. I don't expect > our documentation to be generated as a PDF document for example, so a > full-blown LaTeX seems overkill to me.
mathjax sounds like a reasonable approach assuming we can get it to work in javadoc, which Thomas' link appears to indicate it can. I have not tried to use it in javadoc, but I have used it in my blog and it is pretty easy to use. The nice thing is that there are no extra plugins or dependencies dragged along. I also agree that the embedded TeX will certainly look better than unicode gobledy-gook and that people reading the source will likely be able to make sense of it. Phil > > Luc > >> >>> Pareto distribution is missing >>> ------------------------------ >>> >>> Key: MATH-968 >>> URL: https://issues.apache.org/jira/browse/MATH-968 >>> Project: Commons Math >>> Issue Type: New Feature >>> Affects Versions: 3.2 >>> Reporter: Alex Gryzlov >>> Priority: Minor >>> Attachments: MATH-968.zip >>> >>> >>> Seems that org.apache.commons.math3.distribution lacks a ParetoDistribution >>> for some reason. This is a real common type of distribution, so providing >>> it would be very nice! >> -- >> This message is automatically generated by JIRA. >> If you think it was sent incorrectly, please contact your JIRA administrators >> For more information on JIRA, see: http://www.atlassian.com/software/jira > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] > > --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
