commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gilles Sadowski <gil...@harfang.homelinux.org>
Subject Re: [all] xdoc vs. apt
Date Tue, 18 Sep 2012 13:38:57 GMT
On Tue, Sep 18, 2012 at 02:34:40PM +0200, S├ębastien Brisard wrote:
> 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='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 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...
> 
> >
> > 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.

As you both point out indirectly, the Javadoc system is not exactly suitable
to compose a scientific document. But I remind that its main goal is to
explain the API of a code, not to explain the science that supports the
implementation.
Of course, we can provide some additional hints about the scientific
background, but I do not think that we should go too far in that direction
within the Javadoc. Attempting to write complex stuff (e.g. equations) using
either HTML tables or ASCII art (or any script that amounts to making it
impossible to read the equations directly within the source) would render
the comments useless within the source, forcing the developer to read the
formatted doc if he actually needs that information.
It will also make it a two-step process to check whether the doc is in
agreement with the code. [A second step that will easily be "forgotten".]

If people are interested to provide more in-depth usage and background info,
I suggest that we do it only in the user guide.
My opinion is that such a document should be written in LaTeX (thus made
"universally" available as a PDF file) with all the formatting freedom that
comes with it.

Tutorials should be limited to illustrating selected parts of the library
without using fancy formatting tools. [It's not that I don't like those
tools, but I do not think that CM has the resources to maintain the complex
documents that the API documentation is going to become.]


Best regards,
Gilles

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org


Mime
View raw message