# commons-dev mailing list archives

##### Site index · List index
Message view
Top
From Sébastien Brisard <sebastien.bris...@m4x.org>
Subject Re: [all] xdoc vs. apt
Date Tue, 18 Sep 2012 07:54:54 GMT
Hi Luc,

2012/9/18 luc <luc@spaceroots.org>:
> Le 2012-09-18 07:46, Sébastien Brisard a écrit :
>>
>> Hi,
>
>
> Hi Sébastien,
>
>>
>> 2012/9/18 Sébastien Brisard <sebastien.brisard@m4x.org>:
>>>
>>> Hi,
>>> 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.
>
>
> 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,
Sébastien

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