# commons-dev mailing list archives

##### Site index · List index
Message view
Top
From Sébastien Brisard <sebastien.bris...@m4x.org>
Subject Re: [all] xdoc vs. apt
Date Tue, 18 Sep 2012 18:59:14 GMT
Hi Phil,

2012/9/18 Phil Steitz <phil.steitz@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
>
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.

>
> 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...

>
> 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

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.

> 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-unsubscribe@commons.apache.org