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?
> 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?
>
> 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.
> 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.
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).
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.]
Regards,
Gilles
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org
