Hello Gilles,
2012/9/20 Gilles Sadowski <gil...@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!
>
>> 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 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...
>
> 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...
>
> 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...
Best regards,
Sébastien
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org
