commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From luc <>
Subject Re: [all] xdoc vs. apt
Date Tue, 18 Sep 2012 13:07:59 GMT
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.

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.

This is clearly related also to our migration to svnpubsub as this will 
for sure
force us to change other things too.


> Sébastien
> ---------------------------------------------------------------------
> To unsubscribe, e-mail:
> For additional commands, e-mail:

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

View raw message