commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Phil Steitz <>
Subject Re: [all] xdoc vs. apt
Date Tue, 18 Sep 2012 17:29:01 GMT
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.

> S├ębastien
> ---------------------------------------------------------------------
> To unsubscribe, e-mail:
> For additional commands, e-mail:

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

View raw message