commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sébastien Brisard <>
Subject Re: [all] xdoc vs. apt
Date Tue, 18 Sep 2012 07:54:54 GMT
Hi Luc,

2012/9/18 luc <>:
> Le 2012-09-18 07:46, Sébastien Brisard a écrit :
>> Hi,
> Hi Sébastien,
>> 2012/9/18 Sébastien Brisard <>:
>>> Hi,
>>> thanks for these answers.
>>> I agree that apt does not seem much better than xdoc, but it at least
>>> offers table formatting and so on.
>>> So can anyone recommend a good format? Otherwise, I'm quite happy with
>>> xhtml.
>>> An option I'm going to look at at work is sphinx [1]. It has become
>>> widely spread in the python community and is based on the restructured
>>> text format.
>>> More importantly (for Commons-Math), it supports formulas, either with
>>> dvipng (requires a local installation of LaTeX), or Mathjax (which is
>>> pretty good, and could also be used in xhtml).
> Having something compatible with Mathjax would be a tremendous step forward
> for
> [math]. I would really love to see this happen! Formulas based on dvipng are
> really not good. There are always problems of font sizes (for inline or
> display
> formulas, for some browsers like mobile devices) and they are not friendly
> with
> parsers like search engines or screen readers for visually impaired people.
I agree, it's only a "better-than-nothing" solution.
>>> I can report on my experiments with this format.
> I am really interested in reading about this. On a side note, for another
> project
> I am involved in, do you know if sphinx is compatible with the chiliproject
> forge?
I wouldn't know, as I've never heard of chiliproject forge... However,
Sphinx really seems to be getting bigger and bigger : the whole doc of
Python is written (I understand) with sphinx.

Best regards,

PS: there are other ways to play around with MathML. If you're
interested, I have written a taglet to include MathML in Javadoc.
However, *.mml files become very verbose, I like the MathJax approach
(LaTeX is more compact). Using standard javadoc commands (adding a
line in the header of footer of each page), you can use MathJax in the
javadoc, if you're ever interested...

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message