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 13:42:09 GMT
Hi Luc,

2012/9/18 luc <>:
> Le 2012-09-18 14:34, Sébastien Brisard a écrit :
>> Hi Luc,
>>>>> Having something compatible with Mathjax would be a tremendous step
>>>>> forward
>>>>> for [math]. I would really love to see this happen!
>>>> We can in fact make it happen now! In the site.xml file, we just need
>>>> to add (in the <body></body> section)
>>>> <head>
>>>> <script src=''
>>> Yes, I know about that, but this means our page depend on some external
>>> service which is frowned upon at Apache. If we want to jump to the
>>> MathJax
>>> bandwagon I think we should have a copy of MathJax installed on our
>>> servers.
>>> We could do it ourselves in a dedicated area of our components, but it
>>> may be
>>> better to ask infra about it  before (for the record, MathJax is
>>> distributed under the
>>> terms of the Apache License V2).
>> OK, you already knew about that. I'm sorry.
>>> On the other hand, if we set up the site.xml file to point to a local
>>> installation,
>>> then users who regenerate the site and do not install MathJax by
>>> themselves
>>> would get weird results.
>> I have never tried to install MathJax locally, I understand it's quite
>> a ride. We should spare this to our users...
> It's quite simple (just unzip an archive somewhere yours server has read
> access too).
> However, it is quite large. The zip archive is 17.6 MB (for 2.0) and expand
> to a 136 MB tree.
> So yes, we should spare this to our users.
>>> So at least we have to think a little about it.
>> Another option would be this: since maven-site works with strict xhtml
>> (unlike javadoc), we can embed MathML code in our pages. I'm not sure
>> how we would do it in xdoc or apt, but we can certainly write our
>> user's guide in xhtml (which would not make much of a difference as
>> compared to xdoc). I know MathML is (very) verbose, but our site would
>> then be fully self-sufficient. One approach I use quite consistently
>> is to write MathML objects in *.mml files, which are included in the
>> xhtml file.
> Please, don't go that way. MathML is really tough to write and to read. It
> is something
> that should be done only by tools, it's not an authoring environment.
I won't go this way before we discuss it, of course! I know the
argument about MathML not to be used directly. However, I *have* used
it for lack of a better solution. MathJax is very good, but if I'm
offline, then I can't see my doc properly. However, I thought that
MathJax was both huge and difficult to install. Since it is only
large, I might consider installing it locally.

> Really, MathJax (I think Gilles was the first to suggest it years ago) is a
> very good
> option with its support to simpler syntax than MathML. Perhaps the concerns
> I have
> about hosting the files are stupid. Perhaps even if we decide to host these
> files
> it would be easy to do use local files for our own servers and have the
> regular maven
> build for users use the public cdn files.
That would certainly work, but then our users would not be able to see
the documentation properly if they are off-line.


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

View raw message