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? Sébastien --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
