Hi Gary,
I agree.
Gary Oberbrunner <ga...@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 <wxhgmqzgw...@spammotel.com
>> wrote:
>
>> Eric,
>>
>> Eric Schulte wrote:
>> > "Sebastien Vauban" <wxhgmqzgw...@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
