Mailing-List: contact dev-help@commons.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Commons Developers List" <dev@commons.apache.org>
Received-SPF: pass (athena.apache.org: domain of phil.steitz@gmail.com
 designates 209.85.160.43 as permitted sender)
Message-ID: <505B7B79.5070709@gmail.com>
Date: Thu, 20 Sep 2012 13:24:25 -0700
From: Phil Steitz <phil.steitz@gmail.com>
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7;
 rv:15.0) Gecko/20120907 Thunderbird/15.0.1
MIME-Version: 1.0
To: Commons Developers List <dev@commons.apache.org>
Subject: Re: [math] APT format for the users guide
References: 
 <CAGRH7Ho-6i7zn5NOzOghER91k4cgxBfU-cR1k48zsm4pQEy2TQ@mail.gmail.com>
 <20120920151339.GZ20488@dusk.harfang.homelinux.org>
 <CAGRH7Ho2=9gu+uhP69U72QfV1omSJnUVakd-ogFoUvyj3i9FXQ@mail.gmail.com>
In-Reply-To: 
 <CAGRH7Ho2=9gu+uhP69U72QfV1omSJnUVakd-ogFoUvyj3i9FXQ@mail.gmail.com>
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 8bit

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

Phil
>
> Best regards,
> S�bastien
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>


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