commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sébastien Brisard <sebastien.bris...@m4x.org>
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 <phil.steitz@gmail.com>:
> On 9/20/12 12:01 PM, Sébastien Brisard wrote:
>> Hello Gilles,
>>
>> 2012/9/20 Gilles Sadowski <gilles@harfang.homelinux.org>:
>>> 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.

Sébastien


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org


Mime
View raw message