Hi Gilles,
2012/9/21 Gilles Sadowski <gil...@harfang.homelinux.org>:
> On Fri, Sep 21, 2012 at 04:14:37AM +0200, Sébastien Brisard wrote:
>> 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...
>
> Hold on! I didn't mean that Wiki is to be preferred over Apt. I'd prefer the
> simplest (or best-known) thing that does job i.e.
> * for simple tutorials: Apt (probably)
> * for anything that requires math typesetting: LaTeX.
>
It turns out that my preference goes to apt anyway, I think I'm going
to stick with that format for the userguide of the special package. If
after extensively using it, I still like apt, maybe we could think f
migrating the whole user guide to apt (at that point, I might easily
do that).
> I don't think that it's an advantage to allow HTML tags if we wish to keep
> the doc in a uniform style.
>
Good point. Although it might be handy sometimes to use structuring
tags (not formatting tags!), or even subscript, superscripts (which
are not available in apt). However, in this last case, MathJax should
probably be the answer.
So I guess the next move now is to actually *start* extending the user
guide for special functions, and see if the result is good...
Sébastien
> Best regards,
> Gilles
>
>> Sébastien
>>
>> 2012/9/21 Sébastien Brisard <sebastien.bris...@m4x.org>:
>> > Hi Phil,
>> >
>> > 2012/9/20 Phil Steitz <phil.ste...@gmail.com>:
>> >> On 9/20/12 12:01 PM, Sébastien Brisard wrote:
>> >>> 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!
>> >>
>> >> 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-unsubscr...@commons.apache.org
>> For additional commands, e-mail: dev-h...@commons.apache.org
>>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
> For additional commands, e-mail: dev-h...@commons.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org
