From mboxrd@z Thu Jan 1 00:00:00 1970 From: Eric Schulte Subject: Re: Org-mode as a metalanguage: calling SQL "functions" Date: Fri, 05 Apr 2013 10:31:01 -0600 Message-ID: <87wqshlz22.fsf@gmail.com> References: <87vc85raoh.fsf@ericabrahamsen.net> <87y5d1itxx.fsf@gmail.com> <87mwtgr346.fsf@gmail.com> <16857F81-04F6-4F71-96C2-E9FBBD36BCA0@gmail.com> <87k3ojpwsd.fsf@gmail.com> <86bo9uzdlr.fsf@somewhere.org> <87fvz6qx0q.fsf@gmail.com> <86mwtekqfg.fsf@somewhere.org> Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([208.118.235.92]:43920) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UO9Y3-0001OU-2b for emacs-orgmode@gnu.org; Fri, 05 Apr 2013 12:31:37 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1UO9Xw-0004nf-Ej for emacs-orgmode@gnu.org; Fri, 05 Apr 2013 12:31:31 -0400 Received: from mail-pa0-f50.google.com ([209.85.220.50]:34223) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UO9Xw-0004nL-6G for emacs-orgmode@gnu.org; Fri, 05 Apr 2013 12:31:24 -0400 Received: by mail-pa0-f50.google.com with SMTP id bg2so2099575pad.23 for ; Fri, 05 Apr 2013 09:31:22 -0700 (PDT) List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: Gary Oberbrunner Cc: Orgmode Mailing List Hi Gary, I agree. Gary Oberbrunner 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 > wrote: > >> Eric, >> >> Eric Schulte wrote: >> > "Sebastien Vauban" 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