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:47:06 GMT
Hi Gilles,

> 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.
As a matter of fact, I was talking about the user's guide, not the
Javadoc. But you have a good point on this too, below!

> 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.]
So, I guess you mean the online User's guide should essentially be a
tutorial, while reference material should be provided in a LaTeX file?
I think you have a very good point with maintenance, sorry I have
overlooked that...

In you opinion, would you think that reference values (in ulps) for
the accuracy of special functions should be provided online in the
website, or as a separate document ?
I would favor the online website. If I feel the need for mathematical
formulas, then this part could go in a separate LaTeX file.
What do you think?

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

View raw message