Re: Org-mode as a metalanguage: calling SQL "functions"

[Eric Schulte <schulte.eric@gmail.com>]

Hi Gary,

I agree.

Gary Oberbrunner <garyo@oberbrunner.com> writes:

> 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),

I believe this information is currently split between the following two
manual pages.

    (info "(org)Structure of code blocks")
    (info "(org)var")

> and describe the syntax[es] for *calling* a function in a separate
> section (including how to pass args).

This should be fairly completely addressed in the following manual page.

    (info "(org)Evaluating code blocks")

> 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.
>

Yea, this could be a simple note, e.g., "the method by which variables
are applied to code blocks are language-specific and determined by the
semantics of the programming language of the code block, see ...".

>
> 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).
>

I agree.  I think this information would be best included as a new page
in the manual under the working with source code section.  It could link
to, and be linked from the pages I reference above.

I don't think it'd be overly difficult to write, and shouldn't be more
than a page or two of prose, and as you say it would be very helpful for
beginners.  Alternately this could be a page on Worg, but I think it is
important enough to be included in the manual.

Would you want to take a first pass at such an addition?  If not I can,
but it may be a while before I get to it.

Cheers,

p.s. These two publications could help; a journal article on code blocks
     in Org-mode [1] and a shorter magazine piece on the same [2].  They
     both deal with meta-programming in Org-mode documents.

>
>
>
> 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
>>
>>
>>


Footnotes: 
[1]  http://www.jstatsoft.org/v46/i03

[2]  http://cs.unm.edu/~eschulte/data/CISE-13-3-SciProg.pdf

-- 
Eric Schulte
http://cs.unm.edu/~eschulte