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:14:37 GMT
Hello again,
Gilles mentioned Wiki syntax, and I just realized that Doxia has
built-in support for TWiki. I will give it a go, but the answer should
probably be that it's better than apt (for example, you can use html
tags if you want to).

So maybe what in a few days, I'll be writing the same email, replacing
every occurence of apt with TWiki. I'm experimenting, for the time
being...
Sébastien

2012/9/21 Sébastien Brisard <sebastien.brisard@m4x.org>:
> 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