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.
I don't think that it's an advantage to allow HTML tags if we wish to keep
the doc in a uniform style.
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
