Hello. > Hi Phil, > thanks for your thoughts! > > 2012/9/18 Phil Steitz <phil.ste...@gmail.com>: > > 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. > > > It is theoretically possible. But you would need to embed a link to > the commons-math website. It would be possible, but fairly fragile, to > have the links point to a local install of the commons-math project. > > As for your view on what our doc should/should not be. I think I > agree. I'd like to say it has never been my wish to write a > mathematical treatise (which I would be unable to anyway!). However, > besides usage info, I'd like to provide some details on the > reliability of the proposed implementations. For the special package, > I'm thinking about providing relative error (in ulps) in specific > ranges of the argument. It would come down to a few tables, and > possibly some graphs. Nothing fancy, but I think this is really info > some users might appreciate (I personally am looking for this > information). > > As for mathematical formulas, they would be very limited, in my view.
I would certainly not want to prevent you from providing this information. If you think that xdoc is more convenient than LaTeX for what you have in mind then it's fine. [I guess that it's possible to embed graphics in xdoc (?).] > > > > 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 ;) > > > I am a big fan and long time user of LaTeX. However, I am opposed to > option 2 as unrealistic. That would have a huge maintenance cost, as > there are no such thing as "good coding practices" in LaTeX. Also, I > have experienced writing papers with two-three colleagues, it quickly > leads to horrendous code, everyone writing its own (more or less > overlapping) macros, and so on. I don't even want to imagine that > everyone around should write in the same document... I must be too naive: I didn't think of the userguide's source becoming a mess. ;-) > > > > 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. > > > > Please note that 1) is not a standalone solution. It would have to be > combined with 0) or > > 0bis) Just keep chugging along with the clunky *APT* and its > limitations. I'm sorry to be insisting, but it seems to me that APT > leads to more readable code. > > Another option would be Sphinx. Ralph has done a great job with the > flume website, but referring to what Gilles said in an earlier post, > we should favor the most simple option which fulfills our needs. Maybe > Sphinx is too much. Honestly, I don't know. Maybe that you could do the experiment: use <your preferred tool> in order to show that it's good for the job and easy for newbies to adapt to... I can't say anything really useful. Wasn't there recent posts about a new CMS that could possibly manage the web site? Maybe that the same tool can be used to produce and publish the user guide, the tutorials, and other documents. Best regards, Gilles > > > 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. > > > Again, I don't think 2) is the best (especially from the point of view > of the few people who will still be around in a few years). > xdoc or apt are more limited, but the syntax is so simple that there > is next to no issue regarding "best practices". > > I personally would therefore stay with xdoc/apt + MathJax (if you all > allow me to use apt, otherwise, I'll use xdoc). If we ever feel the > need for more detailed mathematical reference, we can have this > discussion again (but seeing how the user's guide has evolved in the > last year and a half, I doubt this will happen...). > > Best regards, > Sébastien --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
