On 9/18/12 6:47 AM, Sébastien Brisard wrote: > 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?
Let me ask a naive question: is it possible to embed (and easily maintain) hyperlinks in LaTex? I suspect the answer is yes, but I have never done it personally. I would prefer to keep the User Guide as one document / set of hyperlinked documents and have it function more or less as it does now - explain enough of the mathematical background so people understand what the APIs mean and enough code samples so they can quickly figure out how to use them. The first goal overlaps with the javadoc; but in the User Guide a more expository approach can be taken. When combined with examples this is helpful. We seem to have three options: 0) Just keep chugging along with the clunky xdoc and its limitations 1) Use MathJax to basically embed TeX formulas 2) Commit TeX sources and just generate and host pdfs I am not sure the hosting issue is that big a deal on 1), or the performance or lack of online access; but I agree these are negatives. If we can get links to work (especially links to the javadoc), I would be open to 2). The problem there is the monstrous task of translating everything and also the requirement that everyone contributing to the guide be happy with TeX. Most likely the second item is a net positive for most [math] people vis a vis xdoc ;) If the links can be reasonably made to work and maintain, I would lean toward 2). I am not averse to 1) either though and it does have the advantage of being something we could bring in incrementally. Another thing to think about here is which among these is most likely to attract contributions to the documentation. Part of the motivation for adding the User Guide in the first place and to have it included in the site build was to encourage people to contribute to the documentation. We have never really succeeded in getting contributions just to the Guide - i.e., we generally end up having to update it as we prepare for releases as sort of an afterthought. Other projects sometimes attract doco contributors who provide a huge service to the community improving the user documentation. Unfortunately, none of the options above look that appealing from that standpoint. Possibly 2) is the best. I would be interested to hear from others in the community who might be cajoled into helping out with this. Phil > Sébastien > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > For additional commands, e-mail: dev-h...@commons.apache.org > > --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
