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. Thomas --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
