What I'd really like in the org-mode doc somewhere (or on worg?) is the
babel syntax broken out like a traditional programming language, by which I
mean describe the syntax[es] for *defining* a function in one place
(including all the ways to define args and their default values), and
describe the syntax[es] for *calling* a function in a separate section
(including how to pass args).  If the variable semantics vary by language
(as they do), just say so (e.g. when defining a SQL function, vars are
substituted into the body by prefixing the names with $, but in python they
are local vars in non-session mode and global vars in session mode and so
on.  Maybe this doc section shouldn't try to enumerate all those languages,
but just redirect to the proper worg babel language page for details on arg
handling.

I think all this info is already there in one place or another, but IMHO
it's not organized in such a way that a newbie can start to use org-mode as
a metaprogramming language without lots of false starts and reading the
source (like I did).



On Thu, Apr 4, 2013 at 4:10 PM, Sebastien Vauban <wxhgmqzgwmuf@spammotel.com
> wrote:

> Eric,
>
> Eric Schulte wrote:
> > "Sebastien Vauban" <wxhgmqzgwmuf@spammotel.com> writes:
> >> Eric Schulte wrote:
> >>>>> At this point I'm not sure if the documentation or the code should be
> >>>>> amended.  I've personally never liked the args-in-block-name syntax,
> but
> >>>>> I don't recall if we formally decided to abandon it, or if it has
> simply
> >>>>> been broken in a recent commit.
> >>>>
> >>>> I am not sure if I have any say here, but I agree that the args in
> >>>> name notation looks not as good and might be considered for
> >>>> abolishment.
> >>>
> >>> Great, I agree wholeheartedly and I'll update the documentation
> >>> accordingly (and take a look at lob-ingest to ensure it no longer uses
> >>> this var-in-name style).
> >>
> >> I confirm that, following a discussion we had, you had decided to drop
> the
> >> alternate syntax, a couple of months ago (more than 2 ;-)).
> >
> > Great, so I'm not imagining things.  Thanks Seb.
>
> For the sake of clarity, it all began (in September 2011) with the fact it
> was
> more difficult to trap errors such as missing default value, in the
> functional-syntax style. See
> http://article.gmane.org/gmane.emacs.orgmode/46888.
>
> This also lead, a couple of weeks later (October 2011), to questionning the
> multiple keywords used for code blocks, such as #+source: and #+srcname:.
> See
> http://article.gmane.org/gmane.emacs.orgmode/48399.
>
> Best regards,
>   Seb
>
> --
> Sebastien Vauban
>
>
>


-- 
Gary