commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sébastien Brisard <>
Subject Re: [math] APT format for the users guide
Date Fri, 21 Sep 2012 02:05:07 GMT
Hi Phil,

2012/9/20 Phil Steitz <>:
> On 9/20/12 12:01 PM, Sébastien Brisard wrote:
>> Hello Gilles,
>> 2012/9/20 Gilles Sadowski <>:
>>> Hi.
>>>> as I previously said, I'd like to extend the user's guide for the
>>>> special functions package. I am not a big fan of the xdoc format
>>>> currently in use, at is not easily readable. So I thought I would give
>>>> APT a go. Please find below the code corresponding to the current
>>>> "Special Functions" page.
>>> Can it be used to write math symbols/formulae?
>> Nope!
> Can you do the escaping necessary to get MathJax to work embedded?
That you can. You just need to tell maven to add the required
javascript snippet in the header of the generated XHTML files.

>>>> The learning curve is not steep at all (about 5 minutes!). I think
>>>> it's much better (even for tables, which might require a large screen
>>>> ;)).
>>> What's the advantage over the Wiki syntax?
>> None. I just wanted to use "standard" maven enriched text formats. APT
>> is supported out of the box. I am not familiar with Wiki syntax, but
>> I'm sure it's much, much better (as is ReSt). Do you know of any
>> plugin which supports it? Maven badly supports restructured text, for
>> example (which is why I got back to APT).
>>>> The generated pages are identical (I've even reproduced the typo in
>>>> 5.4...), but for the fact that you cannot have anchors with a name
>>>> different from the text they refer to. So anchor {Beta} would be named
>>>> "Beta", and not "beta" as is currently the case. I don't think this is
>>>> much of an issue, as there is no reference to these anchors (I'll
>>>> check the other pages of the user's guide, and update them if
>>>> necessary).
>>>> So, what do you think? Should I pursue, or would you like me to stay
>>>> with the xdoc format?
>>> My opinion is that we should figure out the kind of contents the document
>>> will contain, and choose the (possibly different) language(s) accordingly.
>> Basically, as already emphasized by someone else, APT is no better
>> than the currently used xdoc format, except that the source is
>> definitely readable (hence, more easily maintainable).
> I agree with this and have thought about suggesting this move in the
> past, just never had time or sufficient motivation to do it.
>>>> I would like to emphasize I'm not advocating for a complete switch
>>>> from one format to another. But since I'm going to concentrate on this
>>>> section of the users guide, I thought I might as well choose the
>>>> format which I am most comfortable with. If you do not like the idea
>>>> of having two different formats for the same site, please let me know.
>>> If we can agree to keep the user guide simple (i.e. limited to "To do
>>> <this>, you call <method> with <parameter>, then retrieve the
result as
>>> follows..." etc., with some verbatim code examples), then there is an
>>> advantage to having a source syntax that looks like plain text:
>>>  * simple to write,
>>>  * easy to read.
>> Yes, that's exactly my point of view. From this perspective, I don't
>> think xdoc does the job.
>> In the special package, I want to go a little further (tutorials
>> should not be too difficult: "to compute gamma(x), call
>> Gamma.gamma(x)"...), and give some tables and plots on the accuracy :
>> if 0 <= x <= 8, then logGamma is accurate to within 4 ulps, and so
>> on...
> You can do all of this with xdoc, it is just painful.  You need to
> use html syntax for tables.  The [dbcp] docs have some examples
> showing the pain.
Yes, even the (fairly simple) doc we have is a pain to read.

>>> But if we want to show the math that corresponds to the code, then we loose
>>> everything:
>>>  * difficult to write (either including preprocessed figures or ad-hoc
>>>    syntax)
>>>  * impossible to read (in the source).
>> In an ideal world, we would do this also. But our time is limited...
>> So I'm not sure we need to worry about that for now...
> I am +1 for playing with MathJax embedded where it makes sense.
I also think it would be a good option, as I don't think our needs for
mathematical typesetting are so high. It would be nice if we could
configure the site to fall back to LaTeX + dvipng when MathJax is not
available. I'm not sure how you do that, but it should be possible (I
think Wikipedia offers this possibility).

>>> Loosely related to this discussion: What would you think of splitting the
>>> user guide into several independent tutorials? That would be more in the
>>> spirit of simple "howto"s (as opposed to a sort of "reference" which should
>>> allow for more formatting power, a la LaTeX).
>>> [And that would make it less strange to have different source formats.]
>> That's something to think about. As a side note, APT, although
>> limited, offers the possibility to produce books. That would be nice
>> to have these tutorials on line, and in PDF format (even better:
>> epub!!!).
>> My only worry is: our time is limited...
> I would say stay focused on the simple goals of the guide as it
> exists today.  One thing to check is that generating some sources
> from apt and some from xdoc, we do not have big pain generating the
> integrated site and we can maintain a single table of contents page.
I have tried that locally: apt and xdoc merge seamlessly, and all
generated pages can be linked to the same toc. Apt is not perfect, of
course, but it's much more readable. I could slowly migrate all the
existing xdoc pages to apt if we want to have only one format.


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

View raw message