On 4/28/13 3:19 AM, Thomas Neidhart wrote: > On 04/28/2013 12:08 PM, Thomas Neidhart wrote: >> On 04/27/2013 11: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. >> I experimented a bit with it and it works as described on the linked page: >> >> * add this to the pom.xml in the build/plugins section: >> >> <plugin> >> <groupId>org.apache.maven.plugins</groupId> >> <artifactId>maven-javadoc-plugin</artifactId> >> <configuration> >> <additionalparam>-header '<script >> type="text/javascript" >> src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML"></script>'</additionalparam> >> </configuration> >> </plugin> >> >> * add some formulas to javadoc, e.g. >> >> * The probability distribution function of {@code X} is given by (for >> {@code x >= k}): >> * \( \alpha * k^\alpha / x^{\alpha + 1} \) >> >> this should render inline formulas. >> >> Mathjax supports the same environments as tex/latex (see >> http://en.wikibooks.org/wiki/LaTeX/Mathematics): >> >> * inline formulas: \( ... \) >> * equations: $$ ... $$ or \[ ... \] >> >> the $ ... $ is disabled by default, but could be added via configuration. > ah I forgot, the formulas do not work inside a <pre> tag.
That is probably OK, since most of the time when we use <pre> it is to correctly format formulas :) Phil > > Thomas > > --------------------------------------------------------------------- > 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]
