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

2012/9/18 luc <luc@spaceroots.org>:
> 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)
>>>>
>>>> <script src='http://cdn.mathjax.org/mathjax/latest/MathJax.js'
>>>
>>>
>>>
>>> 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
>>> terms of the Apache License V2).
>>>
>>
>>
>>>
>>> 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
> 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.

Sébastien

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org