commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gilles Sadowski <>
Subject Re: [math] APT format for the users guide
Date Thu, 20 Sep 2012 15:13:39 GMT

> 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
 * difficult to write (either including preprocessed figures or ad-hoc
 * 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.]


To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message