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 <[email protected]>: > Hi Phil, > > 2012/9/20 Phil Steitz <[email protected]>: >> On 9/20/12 12:01 PM, Sébastien Brisard wrote: >>> Hello Gilles, >>> >>> 2012/9/20 Gilles Sadowski <[email protected]>: >>>> 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: [email protected] For additional commands, e-mail: [email protected]
