On Oct 24, 2013 12:58 AM, "Nicolas Goaziou" <n.goaziou@gmail.com> wrote:
> There are two things to consider: what belongs to the manual, and what
> belongs to `org-beamer-environments-extra' docstring.
>
> I think it is reasonable for the manual not to talk about %o, %r... but,
> instead, simply point to the variable name.

OK.

>    Headlines also support 'BEAMER_ACT' and 'BEAMER_OPT' properties. The
> former is translated as an overlay/action specification, or a default
> overlay specification when enclosed within square brackets.  The latter
> specifies options for the current frame or block, and will automatically
> be enclosed within square brackets.

That would help.

I'd still like to see something more like a "for-dummies" explanation of passing options and arguments to LaTeX entities. I'm not saying the documentation is woefully inadequate (hardly that -- Suvayu's page got me rather far, and I got stuck on a couple of details). My experience was: it never would have occurred to me on my own to use the headline text for LaTeX code, and if there was a hint anywhere in the docs to suggest that this would be the way to go, I didn't find it. That's a conceptual leap that passed me by.

FWIW, I often raise a similar point among SuperCollider devs, noting that we generally do a decent job of documenting class interfaces, but not such a great job of explaining to people who don't eat, breathe and sleep SC how to put the pieces together. That leads to questions such as [1] on the mailing list. Really basic use case, but this competent user is confused... meaning, the collective docs aren't doing a thorough job.

This sort of doc would be appropriate for worg, but probably not the manual. If I have time while traveling, I'll draft up a few paragraphs -- but I don't know all the implementation details so I'd certainly need another pair of eyes.

hjh

[1] http://article.gmane.org/gmane.comp.audio.supercollider.user/102850