Re: [O] [RFC] Standardized code block keywords

[Eric Schulte]

Daniel Bausch  writes:

> I did some tests with my documents and they look fine.  Thanks for your work.
>

Great, good to know.

>
> (A minor remark, offtopic: If the document ends just below a source
> code block, no results are inserted when the block is executed.  You
> have to insert an additional blank line, for a result to can appear.)
>

I can't reproduce this problem.

Best -- Eric

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

Re: [O] [RFC] Standardized code block keywords

[Daniel Bausch]

I did some tests with my documents and they look fine.  Thanks for your work.

(A minor remark, offtopic: If the document ends just below a source code 
block, no results are inserted when the block is executed.  You have to insert 
an additional blank line, for a result to can appear.)

Daniel

Am Freitag 28 Oktober 2011, 20:52:48 schrieb Eric Schulte:
> Nick Dokos  writes:
> > Eric Schulte  wrote:
> >> The attached updated patch fixes a bug in the original.
> > 
> > Minor problem in applying:
> > 
> > ,
> > 
> > | $ git apply ~/Mail/inbox/724
> > | /home/nick/Mail/inbox/724:671: trailing whitespace.
> > | #+name:
> > | /home/nick/Mail/inbox/724:599: new blank line at EOF.
> > | +
> > | warning: 2 lines add whitespace errors.
> > 
> > `
> 
> The attached version fixes these issues, Thanks -- Eric

Re: [O] [RFC] Standardized code block keywords

[Nick Dokos]

Thomas S. Dye  wrote:

> And, revising the files before Worg updates the Org-mode it uses will
> break them, right?

Yup - they got to be done at the same time.

Nick

> 
> Tom
> 
> Nick Dokos  writes:
> 
> > I'm trying to add a note to Worg hacks but before I push, I use my local
> > org setup to publish Worg locally and take a look at it (not entirely 
> > reliable
> > since my org version is usually different from the real Worg one, but a
> > good indication of problems before they happen nevertheless). I ran into
> > a couple of problems. 
> >
> > The first one is expected: I'm running with Eric's patch, so when
> > processing Worg/org-contrib/babel/examples/o18.org (Tom Dye's article on
> > Archaelogy in Oceania), I ran into #+srcname vs #+name problems: when
> > Eric's changes do go into org and the new org is used to publish Worg,
> > there is going to be some breakage. Actually, o18.org is the extent of
> > breakage that I saw, so it doesn't look too bad.
> >
> > But I also ran into a second (unrelated) issue. Here's a minimal example:
> >
> > * Conclusion
> >
> > #+begin_src latex 
> >
> > #+end_src
> >
> > Exporting to html gives me the attached backtrace. But the underlying reason
> > is easy to demonstrate: if you C-c C-c on the empty source block, you get:
> >
> > ,
> > | * Conclusion
> > | 
> > | #+begin_src latex 
> > | 
> > | #+end_src
> > | 
> > | #+results:
> > | #+END_LaTeX
> > | #+BEGIN_LaTeX
> > `
> >
> > Nick
> >
> > Versions:
> > Org-mode version 7.7 (release_7.7.485.gcfed6.dirty)
> > GNU Emacs 24.0.90.2 (x86_64-unknown-linux-gnu, GTK+ Version 2.22.0) of 
> > 2011-10-27
> >
> >
> >
> 
> -- 
> Thomas S. Dye
> http://www.tsdye.com
> 

Re: [O] [RFC] Standardized code block keywords

[Thomas S. Dye]

And, revising the files before Worg updates the Org-mode it uses will
break them, right?

Tom

Nick Dokos  writes:

> I'm trying to add a note to Worg hacks but before I push, I use my local
> org setup to publish Worg locally and take a look at it (not entirely reliable
> since my org version is usually different from the real Worg one, but a
> good indication of problems before they happen nevertheless). I ran into
> a couple of problems. 
>
> The first one is expected: I'm running with Eric's patch, so when
> processing Worg/org-contrib/babel/examples/o18.org (Tom Dye's article on
> Archaelogy in Oceania), I ran into #+srcname vs #+name problems: when
> Eric's changes do go into org and the new org is used to publish Worg,
> there is going to be some breakage. Actually, o18.org is the extent of
> breakage that I saw, so it doesn't look too bad.
>
> But I also ran into a second (unrelated) issue. Here's a minimal example:
>
> * Conclusion
>
> #+begin_src latex 
>
> #+end_src
>
> Exporting to html gives me the attached backtrace. But the underlying reason
> is easy to demonstrate: if you C-c C-c on the empty source block, you get:
>
> ,
> | * Conclusion
> | 
> | #+begin_src latex 
> | 
> | #+end_src
> | 
> | #+results:
> | #+END_LaTeX
> | #+BEGIN_LaTeX
> `
>
> Nick
>
> Versions:
> Org-mode version 7.7 (release_7.7.485.gcfed6.dirty)
> GNU Emacs 24.0.90.2 (x86_64-unknown-linux-gnu, GTK+ Version 2.22.0) of 
> 2011-10-27
>
>
>

-- 
Thomas S. Dye
http://www.tsdye.com

Re: [O] [RFC] Standardized code block keywords

[Eric Schulte]

Nick Dokos  writes:

> Eric Schulte  wrote:
>
>> The attached updated patch fixes a bug in the original.
>> 
>
> Minor problem in applying:
>
> ,
> | $ git apply ~/Mail/inbox/724
> | /home/nick/Mail/inbox/724:671: trailing whitespace.
> | #+name: 
> | /home/nick/Mail/inbox/724:599: new blank line at EOF.
> | +
> | warning: 2 lines add whitespace errors.
> `

The attached version fixes these issues, Thanks -- Eric

>From 0e43d59ee8d46a63f86780a502de726271bc39de Mon Sep 17 00:00:00 2001
From: Eric Schulte 
Date: Fri, 28 Oct 2011 10:44:21 -0600
Subject: [PATCH] removing code block, results and call-line synonyms -- BREAKING CHANGE

Following a round of on-list discussion many code block synonyms have
been removed, moving forward the following syntax is valid.

- call lines are specified with #+call:
- code blocks are named with #+name:
- results are named with #+name:, however results generated by a code
  block may still be labeled with #+results:, and tables named with
  #+tblname: will be considered to be named results

The following function may be used to update an existing Org-mode
buffer to the new syntax.

  (defun update-org-buffer ()
"Update an Org-mode buffer to the new data, code block and call line syntax."
(interactive)
(save-excursion
  (flet ((to-re (lst) (concat "^[ \t]*#\\+" (regexp-opt lst t)
  "\\(\\[\\([[:alnum:]]+\\)\\]\\)?\\:[ \t]*"))
 (update (re new)
 (goto-char (point-min))
 (while (re-search-forward re nil t)
   (replace-match new nil nil nil 1
(let ((old-re (to-re '("RESULTS" "DATA" "SRCNAME" "SOURCE")))
  (lob-re (to-re '("LOB")))
  (case-fold-search t))
  (update old-re "name")
  (update lob-re "call")

Note: If an old version of Org-mode (e.g., the one shipped with Emacs)
  is installed on your system many of the important variables will
  be pre-defined with a defvar and *will not* have their values
  automatically updated, these include the following.
  - org-babel-data-names
  - org-babel-result-regexp
  - org-babel-src-block-regexp
  - org-babel-src-name-regexp
  - org-babel-src-name-w-name-regexp
  It may be necessary to either remove the source code of older
  versions of Org-mode, or to explicitly evaluate the ob.el file.

* lisp/ob-exp.el (org-exp-res/src-name-cleanup): Updated
  Documentation.
* lisp/ob-lob.el (org-babel-block-lob-one-liner-regexp): Updated
  regular expression.
  (org-babel-inline-lob-one-liner-regexp): Updated regular expression.
* lisp/ob-ref.el (org-babel-ref-resolve): Notice when something that
  looks like a data results may actually be a code block.
* lisp/ob-table.el: Updated documentation.
* lisp/ob.el (org-babel-src-name-regexp): Simplified regexp.
  (org-babel-get-src-block-info): Updated match strings.
  (org-babel-data-names): Simplified acceptable names.
  (org-babel-find-named-block): Indentation.
  (org-babel-find-named-result): Updated to not return a code block as
  a result.
* lisp/org.el (org-fontify-meta-lines-and-blocks-1): Removing
  references to old syntactic elements.
  (org-additional-option-like-keywords): Removing references to old
  syntactic elements.
* contrib/babel/library-of-babel.org: Updated to make use of the new
  syntax.
* testing/examples/babel-dangerous.org: Updated to make use of the new
  syntax.
* testing/examples/babel.org: Updated to make use of the new syntax.
* testing/examples/ob-awk-test.org: Updated to make use of the new
  syntax.
* testing/examples/ob-fortran-test.org: Updated to make use of the new
  syntax.
* testing/lisp/test-ob.el: Removed two bad tests which tested the
  literal values of old regular expressions rather than their
  behavior.
---
 contrib/babel/library-of-babel.org   |   48 +-
 lisp/ob-exp.el   |2 +-
 lisp/ob-lob.el   |   13 +
 lisp/ob-ref.el   |5 +++
 lisp/ob-table.el |2 +-
 lisp/ob.el   |   31 -
 lisp/org.el  |9 ++
 testing/examples/babel-dangerous.org |5 +++-
 testing/examples/babel.org   |   30 ++--
 testing/examples/ob-awk-test.org |4 +-
 testing/examples/ob-fortran-test.org |4 +-
 testing/lisp/test-ob.el  |   42 -
 12 files changed, 77 insertions(+), 118 deletions(-)

diff --git a/contrib/babel/library-of-babel.org b/contrib/babel/library-of-babel.org
index 2db9d4c..571eb70 100644
--- a/contrib/babel/library-of-babel.org
+++ b/contrib/babel/library-of-babel.org
@@ -22,7 +22,7 @@
 
 A collection of simple utility functions:
 
-#+srcname: echo
+#+name: echo
 #+begin_src emacs-lisp :var input="echo'd"
   input
 #+end_src
@@ -35,7 +35,7 @@ Read the contents of the file at =fil

Re: [O] [RFC] Standardized code block keywords

[Nick Dokos]

Eric Schulte  wrote:

> The attached updated patch fixes a bug in the original.
> 

Minor problem in applying:

,
| $ git apply ~/Mail/inbox/724
| /home/nick/Mail/inbox/724:671: trailing whitespace.
| #+name: 
| /home/nick/Mail/inbox/724:599: new blank line at EOF.
| +
| warning: 2 lines add whitespace errors.
`

Re: [O] [RFC] Standardized code block keywords

[Eric Schulte]

The attached updated patch fixes a bug in the original.

>From 0e43d59ee8d46a63f86780a502de726271bc39de Mon Sep 17 00:00:00 2001
From: Eric Schulte 
Date: Fri, 28 Oct 2011 10:44:21 -0600
Subject: [PATCH] removing code block, results and call-line synonyms -- BREAKING CHANGE

Following a round of on-list discussion many code block synonyms have
been removed, moving forward the following syntax is valid.

- call lines are specified with #+call:
- code blocks are named with #+name:
- results are named with #+name:, however results generated by a code
  block may still be labeled with #+results:, and tables named with
  #+tblname: will be considered to be named results

The following function may be used to update an existing Org-mode
buffer to the new syntax.

  (defun update-org-buffer ()
"Update an Org-mode buffer to the new data, code block and call line syntax."
(interactive)
(save-excursion
  (flet ((to-re (lst) (concat "^[ \t]*#\\+" (regexp-opt lst t)
  "\\(\\[\\([[:alnum:]]+\\)\\]\\)?\\:[ \t]*"))
 (update (re new)
 (goto-char (point-min))
 (while (re-search-forward re nil t)
   (replace-match new nil nil nil 1
(let ((old-re (to-re '("RESULTS" "DATA" "SRCNAME" "SOURCE")))
  (lob-re (to-re '("LOB")))
  (case-fold-search t))
  (update old-re "name")
  (update lob-re "call")

Note: If an old version of Org-mode (e.g., the one shipped with Emacs)
  is installed on your system many of the important variables will
  be pre-defined with a defvar and *will not* have their values
  automatically updated, these include the following.
  - org-babel-data-names
  - org-babel-result-regexp
  - org-babel-src-block-regexp
  - org-babel-src-name-regexp
  - org-babel-src-name-w-name-regexp
  It may be necessary to either remove the source code of older
  versions of Org-mode, or to explicitly evaluate the ob.el file.

* lisp/ob-exp.el (org-exp-res/src-name-cleanup): Updated
  Documentation.
* lisp/ob-lob.el (org-babel-block-lob-one-liner-regexp): Updated
  regular expression.
  (org-babel-inline-lob-one-liner-regexp): Updated regular expression.
* lisp/ob-ref.el (org-babel-ref-resolve): Notice when something that
  looks like a data results may actually be a code block.
* lisp/ob-table.el: Updated documentation.
* lisp/ob.el (org-babel-src-name-regexp): Simplified regexp.
  (org-babel-get-src-block-info): Updated match strings.
  (org-babel-data-names): Simplified acceptable names.
  (org-babel-find-named-block): Indentation.
  (org-babel-find-named-result): Updated to not return a code block as
  a result.
* lisp/org.el (org-fontify-meta-lines-and-blocks-1): Removing
  references to old syntactic elements.
  (org-additional-option-like-keywords): Removing references to old
  syntactic elements.
* contrib/babel/library-of-babel.org: Updated to make use of the new
  syntax.
* testing/examples/babel-dangerous.org: Updated to make use of the new
  syntax.
* testing/examples/babel.org: Updated to make use of the new syntax.
* testing/examples/ob-awk-test.org: Updated to make use of the new
  syntax.
* testing/examples/ob-fortran-test.org: Updated to make use of the new
  syntax.
* testing/lisp/test-ob.el: Removed two bad tests which tested the
  literal values of old regular expressions rather than their
  behavior.
---
 contrib/babel/library-of-babel.org   |   48 +-
 lisp/ob-exp.el   |2 +-
 lisp/ob-lob.el   |   13 +
 lisp/ob-ref.el   |5 +++
 lisp/ob-table.el |2 +-
 lisp/ob.el   |   31 -
 lisp/org.el  |9 ++
 testing/examples/babel-dangerous.org |5 +++-
 testing/examples/babel.org   |   30 ++--
 testing/examples/ob-awk-test.org |4 +-
 testing/examples/ob-fortran-test.org |4 +-
 testing/lisp/test-ob.el  |   42 -
 12 files changed, 77 insertions(+), 118 deletions(-)

diff --git a/contrib/babel/library-of-babel.org b/contrib/babel/library-of-babel.org
index 2db9d4c..571eb70 100644
--- a/contrib/babel/library-of-babel.org
+++ b/contrib/babel/library-of-babel.org
@@ -22,7 +22,7 @@
 
 A collection of simple utility functions:
 
-#+srcname: echo
+#+name: echo
 #+begin_src emacs-lisp :var input="echo'd"
   input
 #+end_src
@@ -35,7 +35,7 @@ Read the contents of the file at =file=.  The =:results vector= and
 =:results scalar= header arguments can be used to read the contents of
 file as either a table or a string.
 
-#+srcname: read
+#+name: read
 #+begin_src emacs-lisp :var file="" :var format=""
   (if (string= format "csv")
   (with-temp-buffer
@@ -49,7 +49,7 @@ file as either a table or a string.
 Write =data= to a file at =file=. 

Re: [O] [RFC] Standardized code block keywords

[Eric Schulte]

The attached patch implements these changes, please see the patch
comment as it contains all of the pertinent information.

If any brave volunteers would be willing to test this patch locally
before I apply it to the Org-mode git repository that would be greatly
appreciated.

Thanks to the test suite the most egregious bugs introduced by my first
version of this patch have already been caught and fixed.

Cheers -- Eric

>From a708aced9e29504637ac1d2ce3203fb796081a7e Mon Sep 17 00:00:00 2001
From: Eric Schulte 
Date: Fri, 28 Oct 2011 10:44:21 -0600
Subject: [PATCH] removing code block, results and call-line synonyms -- BREAKING CHANGE

Following a round of on-list discussion many code block synonyms have
been removed, moving forward the following syntax is valid.

- call lines are specified with #+call:
- code blocks are named with #+name:
- results are named with #+name:, however results generated by a code
  block may still be labeled with #+results:, and tables named with
  #+tblname: will be considered to be named results

The following function may be used to update an existing Org-mode
buffer to the new syntax.

  (defun update-org-buffer ()
"Update an Org-mode buffer to the new data, code block and call line syntax."
(interactive)
(save-excursion
  (flet ((to-re (lst) (concat "^[ \t]*#\\+" (regexp-opt lst t)
  "\\(\\[\\([[:alnum:]]+\\)\\]\\)?\\:[ \t]*"))
 (update (re new)
 (goto-char (point-min))
 (while (re-search-forward re nil t)
   (replace-match new nil nil nil 1
(let ((old-re (to-re '("RESULTS" "DATA" "SRCNAME" "SOURCE")))
  (lob-re (to-re '("LOB")))
  (case-fold-search t))
  (update old-re "name")
  (update lob-re "call")

Note: If an old version of Org-mode (e.g., the one shipped with Emacs)
  is installed on your system many of the important variables will
  be pre-defined with a defvar and *will not* have their values
  automatically updated, these include the following.
  - org-babel-data-names
  - org-babel-result-regexp
  - org-babel-src-block-regexp
  - org-babel-src-name-regexp
  - org-babel-src-name-w-name-regexp
  It may be necessary to either remove the source code of older
  versions of Org-mode, or to explicitly evaluate the ob.el file.

* lisp/ob-exp.el (org-exp-res/src-name-cleanup): Updated
  Documentation.
* lisp/ob-lob.el (org-babel-block-lob-one-liner-regexp): Updated
  regular expression.
  (org-babel-inline-lob-one-liner-regexp): Updated regular expression.
* lisp/ob-ref.el (org-babel-ref-resolve): Notice when something that
  looks like a data results may actually be a code block.
* lisp/ob-table.el: Updated documentation.
* lisp/ob.el (org-babel-src-name-regexp): Simplified regexp.
  (org-babel-get-src-block-info): Updated match strings.
  (org-babel-data-names): Simplified acceptable names.
  (org-babel-find-named-block): Indentation.
  (org-babel-find-named-result): Updated to not return a code block as
  a result.
* lisp/org.el (org-fontify-meta-lines-and-blocks-1): Removing
  references to old syntactic elements.
  (org-additional-option-like-keywords): Removing references to old
  syntactic elements.
* contrib/babel/library-of-babel.org: Updated to make use of the new
  syntax.
* testing/examples/babel-dangerous.org: Updated to make use of the new
  syntax.
* testing/examples/babel.org: Updated to make use of the new syntax.
* testing/examples/ob-awk-test.org: Updated to make use of the new
  syntax.
* testing/examples/ob-fortran-test.org: Updated to make use of the new
  syntax.
* testing/lisp/test-ob.el: Removed two bad tests which tested the
  literal values of old regular expressions rather than their
  behavior.
---
 contrib/babel/library-of-babel.org   |   48 +-
 lisp/ob-exp.el   |2 +-
 lisp/ob-lob.el   |   13 +
 lisp/ob-ref.el   |4 +++
 lisp/ob-table.el |2 +-
 lisp/ob.el   |   30 -
 lisp/org.el  |9 ++
 testing/examples/babel-dangerous.org |5 +++-
 testing/examples/babel.org   |   30 ++--
 testing/examples/ob-awk-test.org |4 +-
 testing/examples/ob-fortran-test.org |4 +-
 testing/lisp/test-ob.el  |   42 -
 12 files changed, 75 insertions(+), 118 deletions(-)

diff --git a/contrib/babel/library-of-babel.org b/contrib/babel/library-of-babel.org
index 2db9d4c..571eb70 100644
--- a/contrib/babel/library-of-babel.org
+++ b/contrib/babel/library-of-babel.org
@@ -22,7 +22,7 @@
 
 A collection of simple utility functions:
 
-#+srcname: echo
+#+name: echo
 #+begin_src emacs-lisp :var input="echo'd"
   input
 #+end_src
@@ -35,7 +35,7 @@ Read the contents of the file at =file=

Re: [O] [RFC] Standardized code block keywords

[Daniel Bausch]

> > Daniel (who used Babel to write his thesis in one big file with all data
> > and chart generating code interleaved with the text -- faboulous!)
> 
> Indeed - could we hope to get a glimpse at some examples (or even the whole
> thing) at some point?

Unfortunately not at the moment, because we're still in the process of getting 
the topic published.
 
> Nick
> 
> PS. I presume it's clear to all that this silliness I started has a big
> smilie wrapped around the whole thing, but just in case somebody decides
> that I'm serious: pthvhtththth :-)

Yeah, that's clear. :-D

Have a nice day
Daniel

Re: [O] [RFC] Standardized code block keywords

[Nick Dokos]

Daniel Bausch  wrote:

> Am Mittwoch 26 Oktober 2011, 15:10:03 schrieb Giovanni Ridolfi:
> > Nick Dokos  writes:
> > > Eric Schulte  wrote:
> > >> Surprisingly (to me) srcname is the winner here, but luckily I haven't
> > >> yet voted, and although I would have though #+source: would have been
> > >> the winner I like the simplicity of using #+name: for named code blocks
> > >> as well as named data.  So I'll vote for #+name: here making it a tie,
> > >> and I'll also take tie-breaking powers upon myself giving #+name: the
> > >> win.
> > > 
> > > This is going to cost you, Schulte! It's not going to go down that
> > > easily. I'll call the FTC, the FCC, the SCOTUS, the POTUS, the NYT, the
> > > BDFL, the NFL and the MLB: an outrage I tell you! An affront to the
> > > democratic rules some of us cherish! We'll fight to the death! Who's
> > > with me?
> > 
> > +1 srcname
> > 
> > :-)
> > 
> > Power to the people! Democracy forever!
> > 
> > Giovanni /who has not used babel yet.
> 
> Hmm, then you don't know what we are talking about and should abstain from 
> voting. ;-)

That's another blatant attempt to subvert democracy by the Schulte
cabal: whoever said that one has to know anything about it before
voting? Both recent and distant history prove that that is not the case
(e.g. watch Ken Burns's "Prohibition" and weep - or laugh - or both).

> --
> Daniel (who used Babel to write his thesis in one big file with all data and 
> chart generating code interleaved with the text -- faboulous!)
> 
> 

Indeed - could we hope to get a glimpse at some examples (or even the whole
thing) at some point?

Nick

PS. I presume it's clear to all that this silliness I started has a big
smilie wrapped around the whole thing, but just in case somebody decides
that I'm serious: pthvhtththth :-)

Re: [O] [RFC] Standardized code block keywords

[Daniel Bausch]

Am Mittwoch 26 Oktober 2011, 15:10:03 schrieb Giovanni Ridolfi:
> Nick Dokos  writes:
> > Eric Schulte  wrote:
> >> Surprisingly (to me) srcname is the winner here, but luckily I haven't
> >> yet voted, and although I would have though #+source: would have been
> >> the winner I like the simplicity of using #+name: for named code blocks
> >> as well as named data.  So I'll vote for #+name: here making it a tie,
> >> and I'll also take tie-breaking powers upon myself giving #+name: the
> >> win.
> > 
> > This is going to cost you, Schulte! It's not going to go down that
> > easily. I'll call the FTC, the FCC, the SCOTUS, the POTUS, the NYT, the
> > BDFL, the NFL and the MLB: an outrage I tell you! An affront to the
> > democratic rules some of us cherish! We'll fight to the death! Who's
> > with me?
> 
> +1 srcname
> 
> :-)
> 
> Power to the people! Democracy forever!
> 
> Giovanni /who has not used babel yet.

Hmm, then you don't know what we are talking about and should abstain from 
voting. ;-)
--
Daniel (who used Babel to write his thesis in one big file with all data and 
chart generating code interleaved with the text -- faboulous!)

Re: [O] [RFC] Standardized code block keywords

[Giovanni Ridolfi]

Nick Dokos  writes:

> Eric Schulte  wrote:
>
>> Surprisingly (to me) srcname is the winner here, but luckily I haven't
>> yet voted, and although I would have though #+source: would have been
>> the winner I like the simplicity of using #+name: for named code blocks
>> as well as named data.  So I'll vote for #+name: here making it a tie,
>> and I'll also take tie-breaking powers upon myself giving #+name: the
>> win.
>> 
>
> This is going to cost you, Schulte! It's not going to go down that easily.
> I'll call the FTC, the FCC, the SCOTUS, the POTUS, the NYT, the BDFL, the
> NFL and the MLB: an outrage I tell you! An affront to the democratic rules
> some of us cherish! We'll fight to the death! Who's with me?

+1 srcname

:-)
Power to the people! Democracy forever!

Giovanni /who has not used babel yet.

Re: [O] [RFC] Standardized code block keywords

[Eric Schulte]

Daniel Bausch  writes:

>> > However, I'd like to ask, what happens, if one refers to a
>> > name of a source block where data is expected, does it then refer to
>> > the results produced by that source block?  How are such situations
>> > handeled at the moment?
>> 
>> Try it out, but be ready to press C-g, because I would guess that it
>> results in an infinite loop.
>
> Isn't it possible to refer to the results of a code block as input data for 
> another?  I thought it was.  If not currently then at least I suppose that it 
> will be in the future.  The new syntax should be ready for that.
>

Sorry for my confusion.  I thought you meant a case in which code block
A needs the results of code block B as an input parameter, but code
block B needs the results of code block A as an input parameter.  Such a
reciprocal dependency would result in an infinite loop.

But yes, the ability of one code block to call another and make use of
its results is (as Tom mentioned) one of the core features of code block
support in Org-mode.

Cheers -- Eric

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

Re: [O] [RFC] Standardized code block keywords

[Thomas S. Dye]

Daniel Bausch  writes:

>> > However, I'd like to ask, what happens, if one refers to a
>> > name of a source block where data is expected, does it then refer to
>> > the results produced by that source block?  How are such situations
>> > handeled at the moment?
>> 
>> Try it out, but be ready to press C-g, because I would guess that it
>> results in an infinite loop.
>
> Isn't it possible to refer to the results of a code block as input data for 
> another?  I thought it was.  If not currently then at least I suppose that it 
> will be in the future.  The new syntax should be ready for that.
>
> Daniel
>
Aloha Daniel,

Yes, it is already possible to refer to named :results as input data for
another source code block.  This is an important feature that makes it
possible to record intermediate results in the Org-mode file.

Also, passing the name of one source code block to a variable of another
source code block is called chaining.  This is an important feature that
makes it possible to do part of a computation in one language and then
another part in a different language, without having to write out
intermediate results.  AFAIK, there is no limit to this chaining
behavior.

I haven't run into an infinite loop doing either of these things,
perhaps because I've not written a source code block that refers to its
own results?

hth,
Tom

-- 
Thomas S. Dye
http://www.tsdye.com

Re: [O] [RFC] Standardized code block keywords

[Daniel Bausch]

Am Dienstag 25 Oktober 2011, 19:21:22 schrieb Nick Dokos:
> Eric Schulte  wrote:
> > Martyn Jago  writes:
> > > Nick Dokos  writes:
> > >> Eric Schulte  wrote:
> > >>> Surprisingly (to me) srcname is the winner here, but luckily I
> > >>> haven't yet voted, and although I would have though #+source: would
> > >>> have been the winner I like the simplicity of using #+name: for
> > >>> named code blocks as well as named data.  So I'll vote for #+name:
> > >>> here making it a tie, and I'll also take tie-breaking powers upon
> > >>> myself giving #+name: the win.
> > >> 
> > >> This is going to cost you, Schulte! It's not going to go down that
> > >> easily. I'll call the FTC, the FCC, the SCOTUS, the POTUS, the NYT,
> > >> the BDFL, the NFL and the MLB: an outrage I tell you! An affront to
> > >> the democratic rules some of us cherish! We'll fight to the death!
> > >> Who's with me?
> > 
> > Ha!
> > 
> > Well at least SCOTUS should be on my side, as they seem to have no
> > problem giving some people more freedom than others.
> 
> Indeed - but what about the NFL? I bet they have more integrity.
> 
> 
> On second thought...
> 
> > > +1 #+name
> 
> Back stabber!

Oops, I didn't want to split the community.  Be nice to each other.

> > Well thank goodness, even if I can't put my own thumb on the scale it
> > seems I can advertise enough to sway voters to my cause. :)
> 
> Bribery and Corruption - what is the world coming to?
> 
> > Cheers -- Eric
> > 
> > > mj

Re: [O] [RFC] Standardized code block keywords

[Daniel Bausch]

> > However, I'd like to ask, what happens, if one refers to a
> > name of a source block where data is expected, does it then refer to
> > the results produced by that source block?  How are such situations
> > handeled at the moment?
> 
> Try it out, but be ready to press C-g, because I would guess that it
> results in an infinite loop.

Isn't it possible to refer to the results of a code block as input data for 
another?  I thought it was.  If not currently then at least I suppose that it 
will be in the future.  The new syntax should be ready for that.

Daniel

Re: [O] [RFC] Standardized code block keywords

[Nick Dokos]

Eric Schulte  wrote:

> Martyn Jago  writes:
> 
> > Nick Dokos  writes:
> >
> >> Eric Schulte  wrote:
> >>
> >>> Surprisingly (to me) srcname is the winner here, but luckily I haven't
> >>> yet voted, and although I would have though #+source: would have been
> >>> the winner I like the simplicity of using #+name: for named code blocks
> >>> as well as named data.  So I'll vote for #+name: here making it a tie,
> >>> and I'll also take tie-breaking powers upon myself giving #+name: the
> >>> win.
> >>> 
> >>
> >> This is going to cost you, Schulte! It's not going to go down that easily.
> >> I'll call the FTC, the FCC, the SCOTUS, the POTUS, the NYT, the BDFL, the
> >> NFL and the MLB: an outrage I tell you! An affront to the democratic rules
> >> some of us cherish! We'll fight to the death! Who's with me?
> >
> 
> Ha!
> 
> Well at least SCOTUS should be on my side, as they seem to have no
> problem giving some people more freedom than others.
> 

Indeed - but what about the NFL? I bet they have more integrity.


On second thought...

> >
> > +1 #+name
> >
> 

Back stabber!

> Well thank goodness, even if I can't put my own thumb on the scale it
> seems I can advertise enough to sway voters to my cause. :)
> 

Bribery and Corruption - what is the world coming to?

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

Re: [O] [RFC] Standardized code block keywords

[Eric Schulte]

Martyn Jago  writes:

> Nick Dokos  writes:
>
>> Eric Schulte  wrote:
>>
>>> Surprisingly (to me) srcname is the winner here, but luckily I haven't
>>> yet voted, and although I would have though #+source: would have been
>>> the winner I like the simplicity of using #+name: for named code blocks
>>> as well as named data.  So I'll vote for #+name: here making it a tie,
>>> and I'll also take tie-breaking powers upon myself giving #+name: the
>>> win.
>>> 
>>
>> This is going to cost you, Schulte! It's not going to go down that easily.
>> I'll call the FTC, the FCC, the SCOTUS, the POTUS, the NYT, the BDFL, the
>> NFL and the MLB: an outrage I tell you! An affront to the democratic rules
>> some of us cherish! We'll fight to the death! Who's with me?
>

Ha!

Well at least SCOTUS should be on my side, as they seem to have no
problem giving some people more freedom than others.

>
> +1 #+name
>

Well thank goodness, even if I can't put my own thumb on the scale it
seems I can advertise enough to sway voters to my cause. :)

Cheers -- Eric

>
> mj
>
>

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

Re: [O] [RFC] Standardized code block keywords

[Martyn Jago]

Nick Dokos  writes:

> Eric Schulte  wrote:
>
>> Surprisingly (to me) srcname is the winner here, but luckily I haven't
>> yet voted, and although I would have though #+source: would have been
>> the winner I like the simplicity of using #+name: for named code blocks
>> as well as named data.  So I'll vote for #+name: here making it a tie,
>> and I'll also take tie-breaking powers upon myself giving #+name: the
>> win.
>> 
>
> This is going to cost you, Schulte! It's not going to go down that easily.
> I'll call the FTC, the FCC, the SCOTUS, the POTUS, the NYT, the BDFL, the
> NFL and the MLB: an outrage I tell you! An affront to the democratic rules
> some of us cherish! We'll fight to the death! Who's with me?

+1 #+name 

mj

Re: [O] [RFC] Standardized code block keywords

[Eric Schulte]

>
> Then maybe #+results for (anonymous) results only, but #+name for anything 
> else from [1] and [3].

This seems like a reasonable approach.

> Wasn't there a concept of linking a results block to its originiating
> source block by some id and we need a place to put the checksum in.

Not that I recall.

> 
> So I see some arguments for treating results special.  But for the
> others I do not see pressing arguments against a common "name" at the
> moment.  However, I'd like to ask, what happens, if one refers to a
> name of a source block where data is expected, does it then refer to
> the results produced by that source block?  How are such situations
> handeled at the moment?

Try it out, but be ready to press C-g, because I would guess that it
results in an infinite loop.

> In other words: is there any type checking?  Type checking could be
> facilitated by using different words, although I think that is not
> neccessary, because there are other means to distinguish the type of a
> block (look at the next line in the buffer).
>

No, there is no type checking in Babel, and the mere thought of
implementing such a features leaves me exhausted.  I think it is safe to
allow users to shoot themselves in the foot if they so please.

Cheers -- Eric

>
> Daniel

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

Re: [O] [RFC] Standardized code block keywords

[Nick Dokos]

Eric Schulte  wrote:

> Surprisingly (to me) srcname is the winner here, but luckily I haven't
> yet voted, and although I would have though #+source: would have been
> the winner I like the simplicity of using #+name: for named code blocks
> as well as named data.  So I'll vote for #+name: here making it a tie,
> and I'll also take tie-breaking powers upon myself giving #+name: the
> win.
> 

This is going to cost you, Schulte! It's not going to go down that easily.
I'll call the FTC, the FCC, the SCOTUS, the POTUS, the NYT, the BDFL, the
NFL and the MLB: an outrage I tell you! An affront to the democratic rules
some of us cherish! We'll fight to the death! Who's with me?




Nobody?




Dang - I'll go back to sleep then.

Re: [O] [RFC] Standardized code block keywords

[Christian Moe]

Surprisingly (to me) srcname is the winner here, but luckily I haven't
yet voted, and although I would have though #+source: would have been
the winner I like the simplicity of using #+name: for named code blocks
as well as named data.


Ditto -- it just wasn't on the table yet when I cast my vote.

Christian

Re: [O] [RFC] Standardized code block keywords

[Eric Schulte]

Alright,

I've tallied up the results and we have the following (with full voting
information below [1]).

Call lines
| call | 13 |

It seems unanimous that remote code block calls should use the #+call:
syntax moving forward.

Data and result names
| (name results)   | 3 |
| name | 2 |
| (data results)   | 2 |
| (object results) | 1 |
| data | 1 |
| object   | 1 |

The Data and result name lines were less straightforward, but I think
the best solution which also seems to be the majority opinion will be to
allow #+name: lines to be used to name results, and in the case of
results of un-named code blocks a #+results: line will be used.

It will also be necessary to allow usage of #+tblname: for as long as
this syntax is used to name tables for Org-mode spreadsheet formulas.

Code block names
| srcname | 5 |
| name| 4 |
| source  | 3 |
| src | 1 |

Surprisingly (to me) srcname is the winner here, but luckily I haven't
yet voted, and although I would have though #+source: would have been
the winner I like the simplicity of using #+name: for named code blocks
as well as named data.  So I'll vote for #+name: here making it a tie,
and I'll also take tie-breaking powers upon myself giving #+name: the
win.

I hope to put together an implementation of this change soon.

Cheers -- Eric

Footnotes: 
[1]  ** eliminate synonyms

#+tblname: code-block-names
| source  | dye   |
| srcname | dokos |
| srcname | moe   |
| srcname | vauban|
| srcname | wagner|
| name| goaziou   |
| srcname | thorsten  |
| source  | rosenfeld |
| name| bausch|
| source  | malone|
| name| moreira   |
| name| fraga |
| src | krug  |

#+tblname: call-lines
| call | dye   |
| call | dokos |
| call | moe   |
| call | vauban|
| call | wagner|
| call | goaziou   |
| call | thorsten  |
| call | rosenfeld |
| call | bausch|
| call | malone|
| call | moreira   |
| call | fraga |
| call | krug  |

#+tblname: data-names
| object   | dye   |
| (data results)   | wagner|
| name | goaziou   |
| (data results)   | rosenfeld |
| (name results)   | bausch|
| data | malone|
| name | moreira   |
| (name results)   | fraga |
| (object results) | krug  |
| (name results)   | vauban|

#+begin_src emacs-lisp :var data=call-lines
  (mapcar (lambda (el) (list (car el) (cdr el)))
  (reduce (lambda (acc vote)
(cons (cons vote (+ 1 (or (cdr (assoc vote acc)) 0)))
  (remove-if (lambda (pair) (equal (car pair) vote)) 
acc)))
  (mapcar #'car data) :initial-value ()))
#+end_src

Call lines
| call | 13 |

Data and result names
| (name results)   | 3 |
| name | 2 |
| (data results)   | 2 |
| (object results) | 1 |
| data | 1 |
| object   | 1 |

Code block names
| srcname | 5 |
| name| 4 |
| source  | 3 |
| src | 1 |


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

Re: [O] [RFC] Standardized code block keywords

[Sebastien Vauban]

Hi Rainer,

Rainer M Krug wrote:
> On Fri, Oct 21, 2011 at 6:24 PM, Eric Schulte wrote:
>>> Just to make it as easy as possible for everyone
>>> Might it be possible to introduce a small flags like "obsolete" and
>>> "stable" (standard)
>>> Old functions, old syntax, etc., might move first to obsolete before
>>> completely removed...
>>> We could open an older file and if it isn't working, we could try
>>>
>>> #+PROPERTY: babel-function-set obsolete
>>
>> I think that making use of such a feature is almost as onerous as changing
>> to the new terms (which is a simple search replace, in fact once terms are
>> selected I'll happily share a function on list which can be used to convert
>> all old terms in existing Org-mode files).
>
> The problem are not every-day users, but if one is not using org-mode not
> using for some time, it might be difficult to figure out what has changed -
> also, I wou't remember in three years time, that these things have changed,
> and run into problems when trying to open an old org-file (in the case of
> literae programming not unlikely).
>
> But I also see your point - Eric.

And the problem is, someday, you will have to remove such functionality
(allowing a smooth transition, thanks to declaring to use an "obsolete"
feature set). So, IMHO, better do it now, once for all...

... if you have:

> a function which checks if these files do include the old / deprecated
> keywords, and inform the user? 

See my modified version of Eric's function:

#+begin_src emacs-lisp
  ;; warn about deprecated feature from version 7.7
  (add-hook 'org-mode-hook
(lambda ()
  (save-excursion
(goto-char (point-min))
(when (re-search-forward (org-make-options-regexp
  '("BABEL")) nil t)
  (display-warning 'org-babel
   (format "This file contains a \"#+BABEL:\" 
line.")
   :warning)
#+end_src

My changes:

- warning in its own window, to be sure to see it (because it's soo easy for
  the message in the echo area to be overwritten by others, if you have many
  hooks doing many things);

- no error when match not found.

> This function could even, in this case here, suggest to do the replacing.
> This function could be over time extended, whenever in-compatible changes
> become necessary - it would be a kind of an org-to-org converter or
> org-version-checker?

See this draft:

#+begin_src emacs-lisp
  (defun my/org-propertyze-babel-line ()
"Play me as many times as needed..."
(interactive)
;; (goto-char (point-min))
;; (search-forward "#+BABEL:")
(search-forward-regexp ":")
(delete-backward-char 2)
(insert "\n#+PROPERTY:  "))
#+end_src

To be used, in its current state, with point placed just after the "#+BABEL:"
keyword.

Best regards,
  Seb

-- 
Sebastien Vauban

Re: [O] [RFC] Standardized code block keywords

[Sebastien Vauban]

Hi Daniel,

Daniel Bausch wrote:
> Am Dienstag 25 Oktober 2011, 03:30:46 schrieb Eric Schulte:
>> "Sebastien Vauban"  writes:
>> > Daniel Bausch wrote:
>> >>>  named code blocks [1] -- "source" "srcname" "function"
> 
> calling external functions [2] -- "call" "lob"
> 
> named data [3] -- "tblname" "resname" "results" "data"
 
 what about "#+name:" for [1] and [3], and "#+call:" for [2] ?
 
 That a table or list contains data is obvious.  The only thing, the
 additional line is for, is to "name" it.
>>> 
>>> As Eric showed us, this is not always to name it... If the table is the
>>> results of an unamed block, you will have #+name: followed by no name!
>>> 
>>> #+name:
>>> | line 1 | data1 |
>>> | line 2 | data2 |
>>> 
>>> what I also find quite disturbing.
>> 
>> I also find this to be disconcerting. -- Eric
>
> Then maybe #+results for (anonymous) results only, but #+name for anything
> else from [1] and [3].

Just wanted to say I like the idea of keeping "results" for (at least) output
of an anonymous call.

Best regards,
  Seb

-- 
Sebastien Vauban

Re: [O] [RFC] Standardized code block keywords

[Jambunathan K]

> #+object_begin var
> x = 1
> y = 2
> #+end

I was thinking on similar lines. This together with Nicolas's suggestion
of "one name" will be wonderful.

I think it is easier to explain what I think by means of an example. In
case of lisp, the SAME variable name could either act as a function or a
variable. The way the VARIABLE NAME is INTERPRETED, DEPENDS ON THE
CONTEXT in which it needs to be interpreted. Similarly a VAR could be
EVALLED or just be a QUOTED SYMBOL.

Coming back to the above example -

If the HANDLE for the above block (whatever you call it), appears as a
PARAM OF BABEL CALL it would be interpreted as a param list. 

Think `apply' and `&rest args' in the elisp world.

Another near equivalent would be COERCING or CASTING. In abstract terms,
the above block could be treated as a TABLE. In some sense, a LIST or a
LIST OF LIST could be coerced in to a TABLE.

I consider babel to be a VM and an execution environment - i.e., as a
scripting environment for Org. So definitely we can borrow ideas from
the existing languages and extend it.

In summary, what I am saying is EVERYTHING IS A BLOB. The way a BLOB is
INTERPRETED depends on the CONTEXT in which interpretation happens. A
BLOB in and of itself is but JUST A BLOB and has NO INHERENT meaning.

I don't use babel myself so I may not be using the right set of
words. Also it is not my intention to hijack the thread.

Jambunathan K.

Re: [O] [RFC] Standardized code block keywords

[Daniel Bausch]

Am Dienstag 25 Oktober 2011, 03:30:46 schrieb Eric Schulte:
> "Sebastien Vauban"  writes:
> > Hi Daniel,
> > 
> > Daniel Bausch wrote:
> >>>  named code blocks [1] -- "source" "srcname" "function"
> >>> 
> >>> calling external functions [2] -- "call" "lob"
> >>> 
> >>> named data [3] -- "tblname" "resname" "results" "data"
> >> 
> >> what about "#+name:" for [1] and [3], and "#+call:" for [2] ?
> >> 
> >> That a table or list contains data is obvious.  The only thing, the
> >> additional line is for, is to "name" it.
> > 
> > As Eric showed us, this is not always to name it... If the table is the
> > results of an unamed block, you will have #+name: followed by no name!
> > 
> > #+name:
> > | line 1 | data1 |
> > | line 2 | data2 |
> > 
> > what I also find quite disturbing.
> 
> I also find this to be disconcerting. -- Eric
> 
> > Best regards,
> > 
> >   Seb

Then maybe #+results for (anonymous) results only, but #+name for anything 
else from [1] and [3].  Wasn't there a concept of linking a results block to 
its originiating source block by some id and we need a place to put the 
checksum in.  So I see some arguments for treating results special.  But for 
the others I do not see pressing arguments against a common "name" at the 
moment.  However, I'd like to ask, what happens, if one refers to a name of a 
source block where data is expected, does it then refer to the results 
produced by that source block?  How are such situations handeled at the 
moment?  In other words: is there any type checking?  Type checking could be 
facilitated by using different words, although I think that is not neccessary, 
because there are other means to distinguish the type of a block (look at the 
next line in the buffer).

Daniel

Re: [O] [RFC] Standardized code block keywords

[Rainer M Krug]

On Tue, Oct 25, 2011 at 8:52 AM, Rainer M Krug  wrote:

>
>
> On Fri, Oct 21, 2011 at 7:37 PM, Sebastien Vauban <
> wxhgmqzgw...@spammotel.com> wrote:
>
>> Hi Eric,
>>
>> Eric Schulte wrote:
>> >> Now, between "srcname" and "source": I'm used to whatever my Yasnippet
>> is
>> >> entering for me. That's currently "srcname". I don't have a strong
>> opinion,
>> >> though, to choose one over the other, except that I like Nick's
>> argument with
>> >> the table analogy.
>> >>
>> >>> I agree on [2] "call".
>> >>
>> >> I clearly agree on "call" as well.
>> >
>> > noted, thanks
>>
>> I think you'll get unanimity on that one.
>>
>> >> Here, I'd like to ask: what about "sbe"?  In my own understanding, it's
>> a
>> >> call, absolutely similar to "call". Is there a technical reason to be
>> forced
>> >> to differentiate both?  If no, can we use "call" as well instead of
>> "sbe"?
>> >
>> > The only difference is that sbe is a function name, and to name a
>> > function call (a function which will take up that term in the entire
>> > Emacs-lisp namespace across all applications) seems somewhat pushy.
>>
>> OK. Point understood. May I suggest to try to find a better name, still?
>>  Once
>> we're at it, modifying one extra line in the documentation won't hurt.
>>
>> I don't know what others find, but I've never understood what it meant.
>> OK,
>> now (since yesterday, in fact), I know it means "source block evaluation",
>> but
>> that's not really intuitive.
>>
>> I'd opt for "ob-call" (package name + "call") or something like that, if I
>> could choose.
>>
>> >>> I'm confused by [3] so I will say nothing for now, except to ask some
>> >>> questions: are we talking about what a human would use to label a
>> piece of
>> >>> data for consumption by a block (including perhaps the future
>> possibilities
>> >>> of lists and paragraphs that Tom brought up)? what babel would use to
>> label
>> >>> a results block (possibly so that it could be consumed by another
>> block in a
>> >>> chain)? both? would that mean that #+tblname would go the way of the
>> dodo
>> >>> and that tables would be labelled with #+data (or #+object or whatever
>> else
>> >>> we come up with)?
>> >>
>> >> For point 3, Eric, I guess that whichever term is chosen, that does not
>> mean
>> >> that "results" will change (I mean: when it's a result of a block
>> execution)?
>>
>> I was expecting you'd always keep "results" for auto-inserted results
>> (after a
>> code block evaluation). But it makes sense to prefer the one term that
>> will
>> win.
>>
>
> I would definitely keep #+results as this marks it as an *output* which can
> change during the next evaluation, and not an input, which has to be
> modified by hand. I would actually go so far and say that #+results *can be*
> src or object (using these terms), but is in itself *not* identifying
> anything, apart from "this is the result of an evaluation". So:
>
> #+results
> #+object_begin
>  .
>  .
>  .
> #+end
>
> would be the result of an evaluation.
>
> One could even, for clarities sake, say that
>
> #+object
>
> if no #+results is in the line before,
>
> is a synonym for
>
> #+input (or #+constant)
> #+object_begin
>  .
>  .
>  .
> #+end
>
> Cheers,
>
> Rainer
>
>
>> > I would be happy for results to change to data or tblname (if a table)
>> > or whatever else is selected.
>>
>> OK, clear.
>>
>> >> In other words, if we choose for "object", we still will have the
>> possibility
>> >> to use "results" (automatically generated) and "object" to refer to
>> something
>> >> we want to use in another call?
>> >>
>> > named data [3] -- "tblname" "resname" "results"
>> "data"
>> >>
>> >> I don't specifically like "resname".
>> >>
>> >> I would keep "results" for automatically generated "results".
>> >>
>> >> I do like "data", but can learn to like "object" as a more generic
>> term,
>> >> future-proof for coming extensions.
>> >
>> > I'll mark you down as undecided for this term. :)
>>
>> Yep!  I'm open to any suggestion you'll make.
>>
>> >> Last remark: we could get one step further and wonder if it wouldn't be
>> good
>> >> to impose a single way to pass variables? We currently have two
>> different
>> >> mechanisms:
>> >>
>> >> #+srcname: convert-date-to-French-format
>> >> #+begin_src sql :var column=""
>> >> CONVERT(varchar(10), $column, 103) AS $column
>> >> #+end_src
>> >>
>> >> and
>> >>
>> >> #+srcname: convert-date-to-French-format(column="")
>> >> #+begin_src sql
>> >> CONVERT(varchar(10), $column, 103) AS $column
>> >> #+end_src
>> >>
>> >> I guess that the first one is easier if we want to construct complex
>> variable
>> >> values (which call Emacs Lisp code or such), but...
>> >
>> > I don't feel that this example causes as much confusion, but if I'm
>> > wrong I am open to change on this front.  Although the only possible
>> > change here would be to remove the second option as the first method of
>> > specifying variables is central to c

Re: [O] [RFC] Standardized code block keywords

[Rainer M Krug]

On Fri, Oct 21, 2011 at 6:24 PM, Eric Schulte wrote:

> > Just to make it as easy as possible for everyone
> > Might it be possible to introduce a small flags like "obsolete" and
> > "stable" (standard)
> > Old functions, old syntax, etc., might move first to obsolete before
> > completely removed...
> > We could open an older file and if it isn't working, we could try
> >
> > #+PROPERTY: babel-function-set obsolete
> >
>
> I think that making use of such a feature is almost as onerous as
> changing to the new terms (which is a simple search replace, in fact
> once terms are selected I'll happily share a function on list which can
> be used to convert all old terms in existing Org-mode files).
>

The problem are not every-day users, but if one is not using org-mode not
using for some time, it might be difficult to figure out what has changed -
also, I wou't remember in three years time, that these things have changed,
and run into problems when trying to open an old org-file (in the case of
literae programming not unlikely).

But I also see your point - Eric.

Would it be an option to include a function which checks if these files do
include the old / deprecated keywords, and inform the user? This function
could even, in this case here, suggest to do the replacing. This function
could be over time extended, whenever in-compatible changes become necessary
- it would be a kind of an org-to-org converter or org-version-checker?


Concerning voting:

Definitely #+call.

I don't like the #+srcname, because most of my blocks are not named, and it
would look weired (I have never used #+tblname but if I also think that that
looks weired if there is no name coming afterwards...).

I would vote for:

#+src

#+object
sounds more "modern" then data.

Just an idea ():

#+object_begin var
  x = 1
  y = 2
#+end

could possible be used for as an alternative for :var ?


And the #+results should stay for generated data to keep them separate (will
/ can be programmatically changed)

Cheers,

Rainer


>
> >
> > if it works, we have to modify the code, because obviously the code
> > requires changed to be compatible in the future. However, just for the
> > moment it is still working. This would give people more time to change
> > there code accordingly. As murphy law tells us one will notice that
> > the particular file is broken exact 5 minutes before the meeting with
> > your boss standing behind you yelling print it, print it  ;)
> >
> > I know git would be perfect to keep the code base frozen for a certain
> > syntax. However, babel is bundled with org-mode which is bundled with
> > Emacs. Thus, it might be very difficult to tell people they have to
> > use org-babel from git with the tag [org-babel_XX] if they want to use
> > there old style files.  AFAIK org-babel does not even come with a own
> > version numbering, right?
> >
> > Alternatively, keep the syntax a little bit longer as it is and create
> > warning messages to point users to future changes (not sure how much
> > time left for emacs24)
> > "Warning: #+lob: in line XX is obsolete, please use #+call: in the
> > future. (manual-link)"
> >
> > To make is short, is is possible to introduce changes "slowly"
> >
>
> I fear this would simply serve to introduce more complexity and
> confusion.
>
>
> >
> > As for voting:
> > [1]
> > #+function: would be what I would expect from other programming
> > languages. Where an unnamed source code block would be something like
> > a lambda function.
> > However, "function" as a term is heavily used in many target languages
> > too. This makes parsing, reading and discussing a bit difficult. ("I
> > called the function foo", "Wait, do you call the org-mode function
> > foo, or the python function foo?")
> > Thus, I vote for #+srcname similar to #+tblname to make sure about the
> > difference between org-babel and the target languages.
> >
> > [2]
> > #+call:, simply because I never can remember "lob" and the acronym is
> > something difficult for newbies.
> >
>
> noted, thanks
>
> >
> > [3]
> > I tend to  #+results: because it fits more to the entire babel syntax.
> > However, earlier on the mailing list people were pointing out that one
> > is going to change "results" for a unknown source block (that was the
> > reason "data" was introduced) and I think this is a valid
> > argument. Maybe "data" and "results" should be both valid if only to
> > pleasure human thinking. However, if I understood correctly, maybe
> > data could be changed to be more some type of constant? That is,
> > #+data: foo can not be changed by a source code block named foo
> > (because it isn't a "result" but "data") but only by human (as a
> > "data" input). Does this make sense?
> >
>
> yes, I'll mark you down for "data and results", which I think is a
> perfectly fine option.
>
> Thanks for sharing -- Eric
>
> >
> > Totti
> >
>
> --
> Eric Schulte
> http://cs.unm.edu/~eschulte/
>
>


-- 
Rainer M. Krug, PhD (Conservation Ecology, SUN), MS

Re: [O] [RFC] Standardized code block keywords

[Eric Schulte]

"Sebastien Vauban"  writes:

> Hi Daniel,
>
> Daniel Bausch wrote:
>>>  named code blocks [1] -- "source" "srcname" "function"
>>> calling external functions [2] -- "call" "lob"
>>> named data [3] -- "tblname" "resname" "results" "data"
>>
>> what about "#+name:" for [1] and [3], and "#+call:" for [2] ?
>>
>> That a table or list contains data is obvious.  The only thing, the 
>> additional 
>> line is for, is to "name" it.
>
> As Eric showed us, this is not always to name it... If the table is the
> results of an unamed block, you will have #+name: followed by no name!
>
> #+name:
> | line 1 | data1 |
> | line 2 | data2 |
>
> what I also find quite disturbing.
>

I also find this to be disconcerting. -- Eric

>
> Best regards,
>   Seb

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

Re: [O] [RFC] Standardized code block keywords

[Darlan Cavalcante Moreira]

Does org have TAB completion in "call lines" for names of blocks that can
be called?  Using "srcname" for blocks of code could make things easier but
if this is not the case then I "name" is just fine.

--
Darlan

At Mon, 24 Oct 2011 08:37:13 +0100,
Eric S Fraga  wrote:
> 
> Daniel Bausch  writes:
> 
> > Hi,
> >
> >>  named code blocks [1] -- "source" "srcname" "function"
> >> calling external functions [2] -- "call" "lob"
> >> named data [3] -- "tblname" "resname" "results" "data"
> >
> > what about "#+name:" for [1] and [3], and "#+call:" for [2] ?
> >
> > That a table or list contains data is obvious.  The only thing, the 
> > additional 
> > line is for, is to "name" it.  That a source block contains source is also 
> > obvious and is already noted by the use of #+begin_src, so why duplicate 
> > the 
> > "src"-part?
> >
> > Daniel
> 
> I don't know if I've left it too late to vote on this but...
> 
> I would go for "name" for [1] and [3] and "call" for [2].
> 
> I can, however, see the need for distinguishing between data tables and
> results so could be convinced that "data" and "results" should be used
> for [3].  In any case, I do know that I dislike srcname and tblname...
> 
> -- 
> : Eric S Fraga (GnuPG: 0xC89193D8FFFCF67D) in Emacs 24.0.90.1
> : using Org-mode version 7.7 (release_7.7.452.g767f5)
> 

Re: [O] [RFC] Standardized code block keywords

[Eric S Fraga]

Daniel Bausch  writes:

> Hi,
>
>>  named code blocks [1] -- "source" "srcname" "function"
>> calling external functions [2] -- "call" "lob"
>> named data [3] -- "tblname" "resname" "results" "data"
>
> what about "#+name:" for [1] and [3], and "#+call:" for [2] ?
>
> That a table or list contains data is obvious.  The only thing, the 
> additional 
> line is for, is to "name" it.  That a source block contains source is also 
> obvious and is already noted by the use of #+begin_src, so why duplicate the 
> "src"-part?
>
> Daniel

I don't know if I've left it too late to vote on this but...

I would go for "name" for [1] and [3] and "call" for [2].

I can, however, see the need for distinguishing between data tables and
results so could be convinced that "data" and "results" should be used
for [3].  In any case, I do know that I dislike srcname and tblname...

-- 
: Eric S Fraga (GnuPG: 0xC89193D8FFFCF67D) in Emacs 24.0.90.1
: using Org-mode version 7.7 (release_7.7.452.g767f5)

Re: [O] [RFC] Standardized code block keywords

[Sebastien Vauban]

Hi Daniel,

Daniel Bausch wrote:
>>  named code blocks [1] -- "source" "srcname" "function"
>> calling external functions [2] -- "call" "lob"
>> named data [3] -- "tblname" "resname" "results" "data"
>
> what about "#+name:" for [1] and [3], and "#+call:" for [2] ?
>
> That a table or list contains data is obvious.  The only thing, the 
> additional 
> line is for, is to "name" it.

As Eric showed us, this is not always to name it... If the table is the
results of an unamed block, you will have #+name: followed by no name!

#+name:
| line 1 | data1 |
| line 2 | data2 |

what I also find quite disturbing.

Best regards,
  Seb

-- 
Sebastien Vauban

Re: [O] [RFC] Standardized code block keywords

[Daniel Bausch]

Am Sonntag 23 Oktober 2011, 18:09:01 schrieben Sie:
> Daniel Bausch  writes:
> > Am Freitag, 21. Oktober 2011, 21:10:27 schrieb Thomas S. Dye:
> >> Eric Schulte  writes:
> >> >>> I'm confused by [3] so I will say nothing for now, except to ask
> >> >>> some questions: are we talking about what a human would use to
> >> >>> label a piece of data for consumption by a block (including perhaps
> >> >>> the future possibilities of lists and paragraphs that Tom brought
> >> >>> up)? what babel would use to label a results block (possibly so
> >> >>> that it could be consumed by another block in a chain)? both? would
> >> >>> that mean that #+tblname would go the way of the dodo and that
> >> >>> tables would be labelled with #+data (or #+object or whatever else
> >> >>> we come up with)?
> >> >> 
> >> >> +1 (Confused, too)
> >> > 
> >> > well, I guess it is good that this discussion has begun if only to
> >> > clear up this lingering uncertainty.
> >> > 
> >> >> I wasn't even aware of #+DATA. Does it do anything TBLNAME and
> >> >> SRCNAME don't?
> >> > 
> >> > from the prospective of code blocks it is exactly synonymous with
> >> > tblname.  Srcname is different in that it labels code blocks.
> >> > 
> >> >> A reason to keep TBLNAME is that it's also used by the spreadsheet
> >> >> remote references. If Babel looked for DATA instead, a table that is
> >> >> both a remote reference for another spreadsheet and a data source for
> >> >> a src block would need both TBLNAME and DATA, which seems redundant.
> >> > 
> >> > agreed, I'm thinking that tblname will at least remain an option no
> >> > matter what decision is made.
> >> > 
> >> >> As for labeling lists and paragraphs, I recall from the list that
> >> >> Nicolas Goaziou is working on a generalized way to set captions,
> >> >> labels and attributes for various kinds of Org block, as is possible
> >> >> now for tables and images. I thought that sounded promising. I don't
> >> >> know if he planned for block names, too (currently we have tblname
> >> >> but no imgname), but that could make sense. In which case it might
> >> >> be a good idea to coordinate.
> >> > 
> >> > Agreed, I was not aware of this work.  Thanks for sharing.  In this
> >> > vein I would like to voice my desire to be able to add captions to
> >> > code blocks, the lack of this feature has bitten me in the past.
> >> 
> >> Hi Eric,
> >> 
> >> For LaTeX export, the listings package has support for code block
> >> captions.
> > 
> > Not in org AFAIK, org only supports these for my use cases not very
> > useful "function name = " exports.  I patched org to produce real
> > captions instead, but my changes are not that well tested and required
> > some changes in the central export logic.  If there is interest I could
> > share what I have so far. The code quality is a mess, as I do not really
> > know elisp.
> > 
> > Daniel
> 
> Yes, source code block captions currently have to be handled outside the
> usual Org-mode mechanism.  If you use org-special-blocks and the
> listings package, then the following template will give you floating
> code block listings with captions in LaTeX export.
> 
>  : #+BEGIN_listing
>  : 
>  :  
>  : 
>  : #+LATEX: \caption[The short caption]{The long caption.}\ref{fig:src_blk}
>  : #+END_listing
> 
> This doesn't do anything for export to other formats, but it works well
> for LaTeX export.  There is even \listoflistings command to produce a
> list of source code listings in the front matter.
> 
> All the best,
> Tom

Thank you for this hint, but with my patches, I'm able to write 

#+caption: A Code Snippet
#+label: lst:xyz
#+begin_src lang
#+end_src

What I'd like to add, is that the listings implementation in org has a bug, 
which I also fixed.  If you mix #+begin_src and #+begin_example blocks in one 
document, then the #+begin_example blocks are syntax highlighted analog to the 
previous #+begin_src block because the language is selected by \lstset.
In my patches I'm using the 'language' attribute of \begin{lstlisting}, which 
does not affect following blocks that do not have this attribute.

I have attached my patch.  I suspect that there might be a bug in it, that 
disables that tables that have #+attr_latex can be used by babel using 
#+tblname, because I observed such a behavior recently.  It is possible that 
this second defect might origin from somewhere else, too.

Daniel
diff --git a/lisp/org-exp.el b/lisp/org-exp.el
index 2aad322..8255021 100644
--- a/lisp/org-exp.el
+++ b/lisp/org-exp.el
@@ -1171,7 +1171,15 @@ on this string to produce the exported version."
   ;; Export code blocks
   (org-export-blocks-preprocess)
 
+  ;; Select and protect backend specific stuff, throw away stuff
+  ;; that is specific for other backends
+  (run-hooks 'org-export-preprocess-before-selecting-backend-code-hook)
+  (org-export-select-backend-specific-text)
+
+  ;; Attach captions to the correct object
+  (setq target-alist (org-export-a

Re: [O] [RFC] Standardized code block keywords

[Torsten Wagner]

Hi Eric,
Hi Seb,



Eric Schulte wrote:

We could open an older file and if it isn't working, we could try

#+PROPERTY: babel-function-set obsolete


I think that making use of such a feature is almost as onerous as
changing to the new terms (which is a simple search replace, in fact
once terms are selected I'll happily share a function on list which can
be used to convert all old terms in existing Org-mode files).


Ok, I agree with both of you. Keeping obsolete functions active might be 
more difficult then just asking people to change the tiny bits and 
pieces. I like the idea to having a function to convert old syntax to 
new syntax (semi)automatically.
Python did the same with there 2to3 script and I was able to convert 
large parts of my scripts without problems.


Only make sure that the BIG BANG is really loud reaching all babelers 
out there (including the ones not on this mailing list and not reading 
changelogs)


Maybe an additional function could be called for a certain time whenever 
old syntax is found (just a list of keywords) generating a warning that 
this code is obsolete pointing to a special chapter in the manual to 
help with conversion. That would help people to understand what is going 
on rather then getting a standard error message for code which run 
perfectly fine a few months ago. Remember, people might upgrade to 
emacs24 and they might not be aware that this includes updates to 
org-mode and org-babel.


Anyhow I would like to offer to help with the manual (my lisp is to poor 
to help with coding). There should be a new section which helps 
old-babeler to change there code to the newest syntax, explain shortly 
changes in the syntax, etc. A two column table is often used for this

| old syntax | replaced now by |
| #+BABEL:   | #+ PROPERTIES   |
Followed by some more explanation or a link to the (rewritten) manual 
section.


Totti

Re: [O] [RFC] Standardized code block keywords

[Thomas S. Dye]

Daniel Bausch  writes:

> Am Freitag, 21. Oktober 2011, 21:10:27 schrieb Thomas S. Dye:
>> Eric Schulte  writes:
>> >>> I'm confused by [3] so I will say nothing for now, except to ask some
>> >>> questions: are we talking about what a human would use to label a piece
>> >>> of data for consumption by a block (including perhaps the future
>> >>> possibilities of lists and paragraphs that Tom brought up)? what babel
>> >>> would use to label a results block (possibly so that it could be
>> >>> consumed by another block in a chain)? both? would that mean
>> >>> that #+tblname would go the way of the dodo and that tables would be
>> >>> labelled with #+data (or #+object or whatever else we come up with)?
>> >> 
>> >> +1 (Confused, too)
>> > 
>> > well, I guess it is good that this discussion has begun if only to clear
>> > up this lingering uncertainty.
>> > 
>> >> I wasn't even aware of #+DATA. Does it do anything TBLNAME and SRCNAME
>> >> don't?
>> > 
>> > from the prospective of code blocks it is exactly synonymous with
>> > tblname.  Srcname is different in that it labels code blocks.
>> > 
>> >> A reason to keep TBLNAME is that it's also used by the spreadsheet
>> >> remote references. If Babel looked for DATA instead, a table that is
>> >> both a remote reference for another spreadsheet and a data source for
>> >> a src block would need both TBLNAME and DATA, which seems redundant.
>> > 
>> > agreed, I'm thinking that tblname will at least remain an option no
>> > matter what decision is made.
>> > 
>> >> As for labeling lists and paragraphs, I recall from the list that
>> >> Nicolas Goaziou is working on a generalized way to set captions,
>> >> labels and attributes for various kinds of Org block, as is possible
>> >> now for tables and images. I thought that sounded promising. I don't
>> >> know if he planned for block names, too (currently we have tblname but
>> >> no imgname), but that could make sense. In which case it might be a
>> >> good idea to coordinate.
>> > 
>> > Agreed, I was not aware of this work.  Thanks for sharing.  In this vein
>> > I would like to voice my desire to be able to add captions to code
>> > blocks, the lack of this feature has bitten me in the past.
>> 
>> Hi Eric,
>> 
>> For LaTeX export, the listings package has support for code block
>> captions.
>
> Not in org AFAIK, org only supports these for my use cases not very useful 
> "function name = " exports.  I patched org to produce real captions instead, 
> but my changes are not that well tested and required some changes in the 
> central export logic.  If there is interest I could share what I have so far. 
>  
> The code quality is a mess, as I do not really know elisp.
>
> Daniel
>
>

Yes, source code block captions currently have to be handled outside the
usual Org-mode mechanism.  If you use org-special-blocks and the
listings package, then the following template will give you floating
code block listings with captions in LaTeX export.

 : #+BEGIN_listing
 :  
 : #+LATEX: \caption[The short caption]{The long caption.}\ref{fig:src_blk}
 : #+END_listing

This doesn't do anything for export to other formats, but it works well
for LaTeX export.  There is even \listoflistings command to produce a
list of source code listings in the front matter.

All the best,
Tom

-- 
Thomas S. Dye
http://www.tsdye.com

Re: [O] [RFC] Standardized code block keywords

[Daniel Bausch]

Hi,

>  named code blocks [1] -- "source" "srcname" "function"
> calling external functions [2] -- "call" "lob"
> named data [3] -- "tblname" "resname" "results" "data"

what about "#+name:" for [1] and [3], and "#+call:" for [2] ?

That a table or list contains data is obvious.  The only thing, the additional 
line is for, is to "name" it.  That a source block contains source is also 
obvious and is already noted by the use of #+begin_src, so why duplicate the 
"src"-part?

Daniel

Re: [O] [RFC] Standardized code block keywords

[Daniel Bausch]

Am Freitag, 21. Oktober 2011, 21:10:27 schrieb Thomas S. Dye:
> Eric Schulte  writes:
> >>> I'm confused by [3] so I will say nothing for now, except to ask some
> >>> questions: are we talking about what a human would use to label a piece
> >>> of data for consumption by a block (including perhaps the future
> >>> possibilities of lists and paragraphs that Tom brought up)? what babel
> >>> would use to label a results block (possibly so that it could be
> >>> consumed by another block in a chain)? both? would that mean
> >>> that #+tblname would go the way of the dodo and that tables would be
> >>> labelled with #+data (or #+object or whatever else we come up with)?
> >> 
> >> +1 (Confused, too)
> > 
> > well, I guess it is good that this discussion has begun if only to clear
> > up this lingering uncertainty.
> > 
> >> I wasn't even aware of #+DATA. Does it do anything TBLNAME and SRCNAME
> >> don't?
> > 
> > from the prospective of code blocks it is exactly synonymous with
> > tblname.  Srcname is different in that it labels code blocks.
> > 
> >> A reason to keep TBLNAME is that it's also used by the spreadsheet
> >> remote references. If Babel looked for DATA instead, a table that is
> >> both a remote reference for another spreadsheet and a data source for
> >> a src block would need both TBLNAME and DATA, which seems redundant.
> > 
> > agreed, I'm thinking that tblname will at least remain an option no
> > matter what decision is made.
> > 
> >> As for labeling lists and paragraphs, I recall from the list that
> >> Nicolas Goaziou is working on a generalized way to set captions,
> >> labels and attributes for various kinds of Org block, as is possible
> >> now for tables and images. I thought that sounded promising. I don't
> >> know if he planned for block names, too (currently we have tblname but
> >> no imgname), but that could make sense. In which case it might be a
> >> good idea to coordinate.
> > 
> > Agreed, I was not aware of this work.  Thanks for sharing.  In this vein
> > I would like to voice my desire to be able to add captions to code
> > blocks, the lack of this feature has bitten me in the past.
> 
> Hi Eric,
> 
> For LaTeX export, the listings package has support for code block
> captions.

Not in org AFAIK, org only supports these for my use cases not very useful 
"function name = " exports.  I patched org to produce real captions instead, 
but my changes are not that well tested and required some changes in the 
central export logic.  If there is interest I could share what I have so far.  
The code quality is a mess, as I do not really know elisp.

Daniel

Re: [O] [RFC] Standardized code block keywords

[Eric Schulte]

>
> Let me help revise the documentation when the dust settles and the
> syntax changes are in place.  As it stands now, #+data: doesn't show up
> in the index to the manual, and the entry for #+tblname: leads only to
> a description of its use in spreadsheets.
>

Thanks Tom, any help with the documentation will be much appreciated.

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

Re: [O] [RFC] Standardized code block keywords

[Viktor Rosenfeld]

Hi Eric,

my preferences are:

- source for code blocks. I think srcname looks ugly (although not as
  ugly as tblname).
- call
- data and results for, well, data and results. With the same semantics
  as Torsten Wagner suggested, i.e. a source block cannot change the
  contents of a data block. It should create a new result block. Data
  should take precedence over result, i.e. only use result blocks for
  input if there is no data block with the name.

Personally, I don't care for tblname and would happilly replace it with
data.

Cheers,
Viktor

Re: [O] [RFC] Standardized code block keywords

[Thomas S. Dye]

Eric Schulte  writes:

>>> I'm confused by [3] so I will say nothing for now, except to ask some
>>> questions: are we talking about what a human would use to label a piece
>>> of data for consumption by a block (including perhaps the future
>>> possibilities of lists and paragraphs that Tom brought up)? what babel
>>> would use to label a results block (possibly so that it could be
>>> consumed by another block in a chain)? both? would that mean
>>> that #+tblname would go the way of the dodo and that tables would be
>>> labelled with #+data (or #+object or whatever else we come up with)?
>>
>> +1 (Confused, too)
>>
>
> well, I guess it is good that this discussion has begun if only to clear
> up this lingering uncertainty.
>
>>
>> I wasn't even aware of #+DATA. Does it do anything TBLNAME and SRCNAME
>> don't?
>>
>
> from the prospective of code blocks it is exactly synonymous with
> tblname.  Srcname is different in that it labels code blocks.
>
>>
>> A reason to keep TBLNAME is that it's also used by the spreadsheet
>> remote references. If Babel looked for DATA instead, a table that is
>> both a remote reference for another spreadsheet and a data source for
>> a src block would need both TBLNAME and DATA, which seems redundant.
>>
>
> agreed, I'm thinking that tblname will at least remain an option no
> matter what decision is made.
>
>>
>> As for labeling lists and paragraphs, I recall from the list that
>> Nicolas Goaziou is working on a generalized way to set captions,
>> labels and attributes for various kinds of Org block, as is possible
>> now for tables and images. I thought that sounded promising. I don't
>> know if he planned for block names, too (currently we have tblname but
>> no imgname), but that could make sense. In which case it might be a
>> good idea to coordinate.
>>
>
> Agreed, I was not aware of this work.  Thanks for sharing.  In this vein
> I would like to voice my desire to be able to add captions to code
> blocks, the lack of this feature has bitten me in the past.

Hi Eric,

For LaTeX export, the listings package has support for code block
captions.

hth,
Tom
-- 
Thomas S. Dye
http://www.tsdye.com

Re: [O] [RFC] Standardized code block keywords

[Thorsten]

Hi Eric,

Eric Schulte  writes:

>  named code blocks [1] -- "source" "srcname" "function"
> calling external functions [2] -- "call" "lob"
> named data [3] -- "tblname" "resname" "results" "data"

here my votes:

[1] -- "srcname"
[2] -- "call" 
[3] -- ? "
I would choose either "tblname" or "data", but I do not oversee all the
implications. 

Cheers
-- 
Thorsten

Re: [O] [RFC] Standardized code block keywords

[Eric Schulte]

> Just to make it as easy as possible for everyone
> Might it be possible to introduce a small flags like "obsolete" and
> "stable" (standard)
> Old functions, old syntax, etc., might move first to obsolete before
> completely removed...
> We could open an older file and if it isn't working, we could try
>
> #+PROPERTY: babel-function-set obsolete
>

I think that making use of such a feature is almost as onerous as
changing to the new terms (which is a simple search replace, in fact
once terms are selected I'll happily share a function on list which can
be used to convert all old terms in existing Org-mode files).

>
> if it works, we have to modify the code, because obviously the code
> requires changed to be compatible in the future. However, just for the
> moment it is still working. This would give people more time to change
> there code accordingly. As murphy law tells us one will notice that
> the particular file is broken exact 5 minutes before the meeting with
> your boss standing behind you yelling print it, print it  ;)
>
> I know git would be perfect to keep the code base frozen for a certain
> syntax. However, babel is bundled with org-mode which is bundled with
> Emacs. Thus, it might be very difficult to tell people they have to
> use org-babel from git with the tag [org-babel_XX] if they want to use
> there old style files.  AFAIK org-babel does not even come with a own
> version numbering, right?
>
> Alternatively, keep the syntax a little bit longer as it is and create
> warning messages to point users to future changes (not sure how much
> time left for emacs24)
> "Warning: #+lob: in line XX is obsolete, please use #+call: in the
> future. (manual-link)"
>
> To make is short, is is possible to introduce changes "slowly"
>

I fear this would simply serve to introduce more complexity and
confusion.


>
> As for voting:
> [1]
> #+function: would be what I would expect from other programming
> languages. Where an unnamed source code block would be something like
> a lambda function.
> However, "function" as a term is heavily used in many target languages
> too. This makes parsing, reading and discussing a bit difficult. ("I
> called the function foo", "Wait, do you call the org-mode function
> foo, or the python function foo?")
> Thus, I vote for #+srcname similar to #+tblname to make sure about the
> difference between org-babel and the target languages.
>
> [2]
> #+call:, simply because I never can remember "lob" and the acronym is
> something difficult for newbies.
>

noted, thanks

>
> [3]
> I tend to  #+results: because it fits more to the entire babel syntax.
> However, earlier on the mailing list people were pointing out that one
> is going to change "results" for a unknown source block (that was the
> reason "data" was introduced) and I think this is a valid
> argument. Maybe "data" and "results" should be both valid if only to
> pleasure human thinking. However, if I understood correctly, maybe
> data could be changed to be more some type of constant? That is,
> #+data: foo can not be changed by a source code block named foo
> (because it isn't a "result" but "data") but only by human (as a
> "data" input). Does this make sense?
>

yes, I'll mark you down for "data and results", which I think is a
perfectly fine option.

Thanks for sharing -- Eric

>
> Totti
>

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

Re: [O] [RFC] Standardized code block keywords

[Thomas S. Dye]

Eric Schulte  writes:

> t...@tsdye.com (Thomas S. Dye) writes:
>
>> Eric Schulte  writes:
>>
 [1] I have the same "annoying" feelings with #+SOURCE, #+SRCNAME, 
 #+FUNCTION,
 #+CALL, #+LOB, and SBE, some of which are interchangeable; some
 not. I'd prefer
 deprecating an old form when a better one is found.
>>>
>>> This point of view has been raised previously both on the mailing list
>>> and in the #org-mode IRC chat room.  I think it is time that we decided
>>> as a community what we want to do about the prevalence of code block
>>> synonyms -- we should make this decision before the release of Emacs24
>>> after which syntax will become harder to change.
>>>
>>> There are currently a number of instances of synonymous keywords when
>>> dealing with code blocks, specifically.
>>>
>>>  named code blocks [1] -- "source" "srcname" "function"
>>> calling external functions [2] -- "call" "lob"
>>> named data [3] -- "tblname" "resname" "results" "data"
>>>
>>> Ideally if we limit each of the above to only one alternative we could
>>> simplify the specification of code blocks in Org-mode making them easier
>>> to learn and use and removing some of the mystery around their syntax.
>>>
>>> What does everyone think?
>>>
>>> Are there suggestions for the best names for each code block entity
>>> (either in the list or not in the list)?
>>>
>>> Are there cases where we want to continue to allow synonyms (e.g., in
>>> named data so that "results" can be used for code block results but
>>> "data" can be used for hand-written data)?
>>>
>>> Thanks -- Eric
>>>
>>> Footnotes: 
>>> [1] named code blocks
>>>
>>> #+source: foo
>>> #+begin_src emacs-lisp
>>>   'foo
>>> #+end_src
>>>
>>> #+srcname: foo
>>> #+begin_src emacs-lisp
>>>   'foo
>>> #+end_src
>>>
>>> #+function: foo
>>> #+begin_src emacs-lisp
>>>   'foo
>>> #+end_src
>>>
>>> [2]  calling external functions
>>>
>>> #+call: foo()
>>>
>>> #+lob: foo()
>>>
>>> [3]  named data
>>>
>>> #+data: something
>>> : something
>>> #+results: something
>>> : something
>>>
>>> etc...
>>
>> Hi Eric,
>>
>> named code blocks [1] "source"
>> calling external functions [2] "call"
>> named data [3] "object"
>>
>
> Noted, thanks, your choices for 1 and 2 are my favorite as well.
>
>>
>> My motivation for [3] "object" instead of the suggested alternates is
>> the hope that it will be possible to name things like lists and
>> paragraphs (that aren't results or data) and pass these objects to
>> source code blocks.
>>
>
> I would say that I would consider paragraphs and lists to be "data" as
> well, but I think object is a fine alternative.  Also, lists are already
> a supported data type.
>
> #+data: something
> - 1
> - 2
> - 3
>
> #+begin_src emacs-lisp :var it=something :results list
>   (reverse it)
> #+end_src
>
> #+results:
> - 3
> - 2
> - 1
>
> Thanks for sharing -- Eric
>
>>
>> All the best,
>> Tom

Hi Eric,

Let me help revise the documentation when the dust settles and the
syntax changes are in place.  As it stands now, #+data: doesn't show up
in the index to the manual, and the entry for #+tblname: leads only to
a description of its use in spreadsheets.

I should have known lists are already supported.  Great work!

All the best,
Tom

-- 
Thomas S. Dye
http://www.tsdye.com

Re: [O] [RFC] Standardized code block keywords

[Eric Schulte]

So far I have the following.

code block names
| source  | dye |
| srcname | dokos   |
| srcname | moe |
| srcname | vauban  |
| srcname | wagner  |
| name| goaziou |

call lines
| call | dye |
| call | dokos   |
| call | moe |
| call | vauban  |
| call | wagner  |
| call | goaziou |

data names
| object | dye |
| (data results) | wagner  |
| name   | goaziou |

It seems that srcname is pulling ahead for naming code blocks (to my
surprise) and that call is the clear winner for call lines.  labeling
data is certainly less obvious and has tricky entanglements with other
parts of Org-mode (e.g., tables will likely continue to be named with
tblname).

I'll likely be out of contact for the remainder of the weekend but when
I'm back I'll update tallies and we can see where the consensus stands.
Thanks to everyone who has or will reply, I think the best way to find
the most natural options for these decisions is through surveys and it
is great to have a community so willing to help.

Cheers -- Eric

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

Re: [O] [RFC] Standardized code block keywords

[Sebastien Vauban]

Hi Eric and Torsten,

Eric Schulte wrote:
>> We could open an older file and if it isn't working, we could try
>>
>> #+PROPERTY: babel-function-set obsolete
>
> I think that making use of such a feature is almost as onerous as
> changing to the new terms (which is a simple search replace, in fact
> once terms are selected I'll happily share a function on list which can
> be used to convert all old terms in existing Org-mode files).

I also think, for the sake of the efficiency we're trying to achieve, that we
must forget about the past in one "big bang" (v7.8 or whatever). Supporting it
temporarily in v7.8 and not anymore in 7.9 won't really help, IMHO.

Of course, it must be clearly stated that this change will break every old
report. That must be the first visible item of the description of 7.8.

Regarding a function to automate the changes, this is what I used this
afternoon (quite dumb, certainly to be improved):

#+begin_src emacs-lisp
(defun my/org-propertyze-babel-line ()
  (interactive)
  (search-forward-regexp ":")
  (delete-backward-char 2)
  (insert "\n#+PROPERTY:  "))
#+end_src

Put point after `#+BABEL:' and apply it as many times as needed.

Best regards,
  Seb

-- 
Sebastien Vauban

Re: [O] [RFC] Standardized code block keywords

[Eric Schulte]

"Sebastien Vauban"  writes:

> Hi Torsten,
>
> Torsten Wagner wrote:
>> I tend to  #+results: because it fits more to the entire babel syntax.
>> However, earlier on the mailing list people were pointing out that one
>> is going to change "results" for a unknown source block (that was the
>> reason "data" was introduced) and I think this is a valid
>> argument. Maybe "data" and "results" should be both valid if only to
>> pleasure human thinking. However, if I understood correctly, maybe
>> data could be changed to be more some type of constant? That is,
>> #+data: foo can not be changed by a source code block named foo
>> (because it isn't a "result" but "data") but only by human (as a
>> "data" input). Does this make sense?
>
> Yes, #+results are automatically generated by execution of some code.
>
> But, if you want to start with something, not generated, you had to insert
> yourself a #+results block until the more logical #+data had been introduced.
>
> I like your explanation about the fact that such a manually-entered block is
> "constant".
>

I like "constant" too, but the goals is to remove synonyms, not add
them. :)

Thanks -- Eric

>
> Best regards,
>   Seb

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

Re: [O] [RFC] Standardized code block keywords

[Sebastien Vauban]

Hi Eric,

Eric Schulte wrote:
>> Now, between "srcname" and "source": I'm used to whatever my Yasnippet is
>> entering for me. That's currently "srcname". I don't have a strong opinion,
>> though, to choose one over the other, except that I like Nick's argument with
>> the table analogy.
>>
>>> I agree on [2] "call".
>>
>> I clearly agree on "call" as well.
>
> noted, thanks

I think you'll get unanimity on that one.

>> Here, I'd like to ask: what about "sbe"?  In my own understanding, it's a
>> call, absolutely similar to "call". Is there a technical reason to be forced
>> to differentiate both?  If no, can we use "call" as well instead of "sbe"?
>
> The only difference is that sbe is a function name, and to name a
> function call (a function which will take up that term in the entire
> Emacs-lisp namespace across all applications) seems somewhat pushy.

OK. Point understood. May I suggest to try to find a better name, still?  Once
we're at it, modifying one extra line in the documentation won't hurt.

I don't know what others find, but I've never understood what it meant. OK,
now (since yesterday, in fact), I know it means "source block evaluation", but
that's not really intuitive.

I'd opt for "ob-call" (package name + "call") or something like that, if I
could choose.

>>> I'm confused by [3] so I will say nothing for now, except to ask some
>>> questions: are we talking about what a human would use to label a piece of
>>> data for consumption by a block (including perhaps the future possibilities
>>> of lists and paragraphs that Tom brought up)? what babel would use to label
>>> a results block (possibly so that it could be consumed by another block in a
>>> chain)? both? would that mean that #+tblname would go the way of the dodo
>>> and that tables would be labelled with #+data (or #+object or whatever else
>>> we come up with)?
>>
>> For point 3, Eric, I guess that whichever term is chosen, that does not mean
>> that "results" will change (I mean: when it's a result of a block execution)?

I was expecting you'd always keep "results" for auto-inserted results (after a
code block evaluation). But it makes sense to prefer the one term that will
win.

> I would be happy for results to change to data or tblname (if a table)
> or whatever else is selected.

OK, clear.

>> In other words, if we choose for "object", we still will have the possibility
>> to use "results" (automatically generated) and "object" to refer to something
>> we want to use in another call?
>>
> named data [3] -- "tblname" "resname" "results" "data"
>>
>> I don't specifically like "resname".
>>
>> I would keep "results" for automatically generated "results".
>>
>> I do like "data", but can learn to like "object" as a more generic term,
>> future-proof for coming extensions.
>
> I'll mark you down as undecided for this term. :)

Yep!  I'm open to any suggestion you'll make.

>> Last remark: we could get one step further and wonder if it wouldn't be good
>> to impose a single way to pass variables? We currently have two different
>> mechanisms:
>>
>> #+srcname: convert-date-to-French-format
>> #+begin_src sql :var column=""
>> CONVERT(varchar(10), $column, 103) AS $column
>> #+end_src
>>
>> and
>>
>> #+srcname: convert-date-to-French-format(column="")
>> #+begin_src sql
>> CONVERT(varchar(10), $column, 103) AS $column
>> #+end_src
>>
>> I guess that the first one is easier if we want to construct complex variable
>> values (which call Emacs Lisp code or such), but...
>
> I don't feel that this example causes as much confusion, but if I'm
> wrong I am open to change on this front.  Although the only possible
> change here would be to remove the second option as the first method of
> specifying variables is central to code block management.

Just that I remember both syntaxes weren't handled the same way for error
reporting (remember, when there is no default value: in one case, you can get
the name of the faulty block; in the other, not), and that makes me think is
not as simple as an alias. Hence, your Babel code is or can become different
just because there are different alternatives to write certain things down.

Then, as a user, I always wonder what's the best one?  "For a good error
reporting (with the name of the code block being outputted), which one do I
have to use?" and such questions...

If we only have one way, we can be sure everybody experiences the same things
with the same semantical input.

Another point, that may or may not have much to do with this, is that I don't
have anymore the source name exported in HTML -- dunno when it disappeared,
though. I remember that, at some point, it was due to having, or not, a
default value (at the time, having no default value was still allowed), but
now, even with the default values for every var, I miss those names in the
HTML (for literate programming support, it is quite useful to be able to see
the name of the block along wit

Re: [O] [RFC] Standardized code block keywords

[Eric Schulte]

>
> Now, between "srcname" and "source": I'm used to whatever my Yasnippet is
> entering for me. That's currently "srcname". I don't have a strong opinion,
> though, to choose one over the other, except that I like Nick's argument with
> the table analogy.
>
>> I agree on [2] "call".
>
> I clearly agree on "call" as well.
>

noted, thanks

>
> Here, I'd like to ask: what about "sbe"?  In my own understanding, it's a
> call, absolutely similar to "call". Is there a technical reason to be forced
> to differentiate both?  If no, can we use "call" as well instead of "sbe"?
>

The only difference is that sbe is a function name, and to name a
function call (a function which will take up that term in the entire
Emacs-lisp namespace across all applications) seems somewhat pushy.

>
>> I'm confused by [3] so I will say nothing for now, except to ask some
>> questions: are we talking about what a human would use to label a piece of
>> data for consumption by a block (including perhaps the future possibilities
>> of lists and paragraphs that Tom brought up)? what babel would use to label
>> a results block (possibly so that it could be consumed by another block in a
>> chain)? both? would that mean that #+tblname would go the way of the dodo
>> and that tables would be labelled with #+data (or #+object or whatever else
>> we come up with)?
>
> For point 3, Eric, I guess that whichever term is chosen, that does not mean
> that "results" will change (I mean: when it's a result of a block execution)?
>

I would be happy for results to change to data or tblname (if a table)
or whatever else is selected.

>
> In other words, if we choose for "object", we still will have the possibility
> to use "results" (automatically generated) and "object" to refer to something
> we want to use in another call?
>
 named data [3] -- "tblname" "resname" "results" "data"
>
> I don't specifically like "resname".
>
> I would keep "results" for automatically generated "results".
>
> I do like "data", but can learn to like "object" as a more generic term,
> future-proof for coming extensions.
>

I'll mark you down as undecided for this term. :)

>
> Last remark: we could get one step further and wonder if it wouldn't be good
> to impose a single way to pass variables? We currently have two different
> mechanisms:
>
> #+srcname: convert-date-to-French-format
> #+begin_src sql :var column=""
> CONVERT(varchar(10), $column, 103) AS $column
> #+end_src
>
> and
>
> #+srcname: convert-date-to-French-format(column="")
> #+begin_src sql
> CONVERT(varchar(10), $column, 103) AS $column
> #+end_src
>
> I guess that the first one is easier if we want to construct complex variable
> values (which call Emacs Lisp code or such), but...
>

I don't feel that this example causes as much confusion, but if I'm
wrong I am open to change on this front.  Although the only possible
change here would be to remove the second option as the first method of
specifying variables is central to code block management.

>
> Thanks for your comments...
>

Thanks for your feedback, Best -- Eric

>
> Best regards,
>   Seb

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

Re: [O] [RFC] Standardized code block keywords

[Eric Schulte]

Nicolas Goaziou  writes:

> Hello,
>
> Eric Schulte  writes:
>
>> There are currently a number of instances of synonymous keywords when
>> dealing with code blocks, specifically.
>>
>>  named code blocks [1] -- "source" "srcname" "function"
>> calling external functions [2] -- "call" "lob"
>> named data [3] -- "tblname" "resname" "results" "data"
>>
>
> - Cases [1] and [2] : I'd suggest to drop all of them and to use "name",
>   shared by both source code and data. Is it really different to name
>   a source block or a list?
>

I think you mean [1] and [3] in the above, and I agree, these could
easily be the same term and "name" has a nice generality to it.
Although it is unintuitive in the case of un-named data, e.g.,

#+name:
| 1 |
| 2 |
| 3 |

looks weird to me.

>
> - Case [3] : I like "call". "lob" is too cryptic.
>

assuming you mean [2] above, I think call is emerging as the clear
winner in this case.

>
>> Are there cases where we want to continue to allow synonyms (e.g., in
>> named data so that "results" can be used for code block results but
>> "data" can be used for hand-written data)?
>
> No. One Keyword to name them all.
>

Noted, Thanks for the input -- Eric

>
> Regards,
>
> [1] DEFINITION NOT FOUND: 1
>
> [2] DEFINITION NOT FOUND: 3
>
> [3] DEFINITION NOT FOUND: 2

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

Re: [O] [RFC] Standardized code block keywords

[Eric Schulte]

>> I'm confused by [3] so I will say nothing for now, except to ask some
>> questions: are we talking about what a human would use to label a piece
>> of data for consumption by a block (including perhaps the future
>> possibilities of lists and paragraphs that Tom brought up)? what babel
>> would use to label a results block (possibly so that it could be
>> consumed by another block in a chain)? both? would that mean
>> that #+tblname would go the way of the dodo and that tables would be
>> labelled with #+data (or #+object or whatever else we come up with)?
>
> +1 (Confused, too)
>

well, I guess it is good that this discussion has begun if only to clear
up this lingering uncertainty.

>
> I wasn't even aware of #+DATA. Does it do anything TBLNAME and SRCNAME
> don't?
>

from the prospective of code blocks it is exactly synonymous with
tblname.  Srcname is different in that it labels code blocks.

>
> A reason to keep TBLNAME is that it's also used by the spreadsheet
> remote references. If Babel looked for DATA instead, a table that is
> both a remote reference for another spreadsheet and a data source for
> a src block would need both TBLNAME and DATA, which seems redundant.
>

agreed, I'm thinking that tblname will at least remain an option no
matter what decision is made.

>
> As for labeling lists and paragraphs, I recall from the list that
> Nicolas Goaziou is working on a generalized way to set captions,
> labels and attributes for various kinds of Org block, as is possible
> now for tables and images. I thought that sounded promising. I don't
> know if he planned for block names, too (currently we have tblname but
> no imgname), but that could make sense. In which case it might be a
> good idea to coordinate.
>

Agreed, I was not aware of this work.  Thanks for sharing.  In this vein
I would like to voice my desire to be able to add captions to code
blocks, the lack of this feature has bitten me in the past.

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

Re: [O] [RFC] Standardized code block keywords

[Eric Schulte]

t...@tsdye.com (Thomas S. Dye) writes:

> Eric Schulte  writes:
>
>>> [1] I have the same "annoying" feelings with #+SOURCE, #+SRCNAME, 
>>> #+FUNCTION,
>>> #+CALL, #+LOB, and SBE, some of which are interchangeable; some
>>> not. I'd prefer
>>> deprecating an old form when a better one is found.
>>
>> This point of view has been raised previously both on the mailing list
>> and in the #org-mode IRC chat room.  I think it is time that we decided
>> as a community what we want to do about the prevalence of code block
>> synonyms -- we should make this decision before the release of Emacs24
>> after which syntax will become harder to change.
>>
>> There are currently a number of instances of synonymous keywords when
>> dealing with code blocks, specifically.
>>
>>  named code blocks [1] -- "source" "srcname" "function"
>> calling external functions [2] -- "call" "lob"
>> named data [3] -- "tblname" "resname" "results" "data"
>>
>> Ideally if we limit each of the above to only one alternative we could
>> simplify the specification of code blocks in Org-mode making them easier
>> to learn and use and removing some of the mystery around their syntax.
>>
>> What does everyone think?
>>
>> Are there suggestions for the best names for each code block entity
>> (either in the list or not in the list)?
>>
>> Are there cases where we want to continue to allow synonyms (e.g., in
>> named data so that "results" can be used for code block results but
>> "data" can be used for hand-written data)?
>>
>> Thanks -- Eric
>>
>> Footnotes: 
>> [1] named code blocks
>>
>> #+source: foo
>> #+begin_src emacs-lisp
>>   'foo
>> #+end_src
>>
>> #+srcname: foo
>> #+begin_src emacs-lisp
>>   'foo
>> #+end_src
>>
>> #+function: foo
>> #+begin_src emacs-lisp
>>   'foo
>> #+end_src
>>
>> [2]  calling external functions
>>
>> #+call: foo()
>>
>> #+lob: foo()
>>
>> [3]  named data
>>
>> #+data: something
>> : something
>> #+results: something
>> : something
>>
>> etc...
>
> Hi Eric,
>
> named code blocks [1] "source"
> calling external functions [2] "call"
> named data [3] "object"
>

Noted, thanks, your choices for 1 and 2 are my favorite as well.

>
> My motivation for [3] "object" instead of the suggested alternates is
> the hope that it will be possible to name things like lists and
> paragraphs (that aren't results or data) and pass these objects to
> source code blocks.
>

I would say that I would consider paragraphs and lists to be "data" as
well, but I think object is a fine alternative.  Also, lists are already
a supported data type.

#+data: something
- 1
- 2
- 3

#+begin_src emacs-lisp :var it=something :results list
  (reverse it)
#+end_src

#+results:
- 3
- 2
- 1

Thanks for sharing -- Eric

>
> All the best,
> Tom

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

Re: [O] [RFC] Standardized code block keywords

[Eric Schulte]

>
> I disagree with Tom on [1]: it should clearly be "srcname", in analogy
> to #+tblname - and also so I don't have to change my files :-} (but see
> my question about tblname below).
>
> I agree on [2] "call".
>

noted

>
> I'm confused by [3] so I will say nothing for now, except to ask some
> questions: are we talking about what a human would use to label a piece
> of data for consumption by a block (including perhaps the future
> possibilities of lists and paragraphs that Tom brought up)?

Yes, and lists are already supported.  Supporting paragraphs would not
be difficult.

> what babel would use to label a results block (possibly so that it
> could be consumed by another block in a chain)? both?

yes

> would that mean that #+tblname would go the way of the dodo and that
> tables would be labelled with #+data (or #+object or whatever else we
> come up with)?
>

I am hesitant to suggest changing #+tblname: as it is used throughout
the rest of Org-mode, so it may be that whatever choice is made here
tblname will remain a synonymous option.

Thanks -- Eric

>
> Thanks,
> Nick
>

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

Re: [O] [RFC] Standardized code block keywords

[Nicolas Goaziou]

Hello,

Eric Schulte  writes:

> There are currently a number of instances of synonymous keywords when
> dealing with code blocks, specifically.
>
>  named code blocks [1] -- "source" "srcname" "function"
> calling external functions [2] -- "call" "lob"
> named data [3] -- "tblname" "resname" "results" "data"
>

- Cases [1] and [2] : I'd suggest to drop all of them and to use "name",
  shared by both source code and data. Is it really different to name
  a source block or a list?

- Case [3] : I like "call". "lob" is too cryptic.

> Are there cases where we want to continue to allow synonyms (e.g., in
> named data so that "results" can be used for code block results but
> "data" can be used for hand-written data)?

No. One Keyword to name them all.

Regards,

[1] DEFINITION NOT FOUND: 1

[2] DEFINITION NOT FOUND: 3

[3] DEFINITION NOT FOUND: 2

-- 
Nicolas Goaziou

Re: [O] [RFC] Standardized code block keywords

[Sebastien Vauban]

Hi Torsten,

Torsten Wagner wrote:
> I tend to  #+results: because it fits more to the entire babel syntax.
> However, earlier on the mailing list people were pointing out that one
> is going to change "results" for a unknown source block (that was the
> reason "data" was introduced) and I think this is a valid
> argument. Maybe "data" and "results" should be both valid if only to
> pleasure human thinking. However, if I understood correctly, maybe
> data could be changed to be more some type of constant? That is,
> #+data: foo can not be changed by a source code block named foo
> (because it isn't a "result" but "data") but only by human (as a
> "data" input). Does this make sense?

Yes, #+results are automatically generated by execution of some code.

But, if you want to start with something, not generated, you had to insert
yourself a #+results block until the more logical #+data had been introduced.

I like your explanation about the fact that such a manually-entered block is
"constant".

Best regards,
  Seb

-- 
Sebastien Vauban

Re: [O] [RFC] Standardized code block keywords

[Sebastien Vauban]

Hi Nick, Tom, Eric and all,

Nick Dokos wrote:
> Thomas S. Dye  wrote:
>> Eric Schulte  writes:
>> 
 [1] I have the same "annoying" feelings with #+SOURCE, #+SRCNAME, 
 #+FUNCTION,
 #+CALL, #+LOB, and SBE, some of which are interchangeable; some
 not. I'd prefer deprecating an old form when a better one is found.
>>>
>>> This point of view has been raised previously both on the mailing list
>>> and in the #org-mode IRC chat room. I think it is time that we decided as
>>> a community what we want to do about the prevalence of code block
>>> synonyms -- we should make this decision before the release of Emacs24
>>> after which syntax will become harder to change.

Thanks for tackling this.

>>> There are currently a number of instances of synonymous keywords when
>>> dealing with code blocks, specifically.
>>>
>>>  named code blocks [1] -- "source" "srcname" "function"
>>> calling external functions [2] -- "call" "lob"
>>> named data [3] -- "tblname" "resname" "results" "data"
>>>
>>> Ideally if we limit each of the above to only one alternative we could
>>> simplify the specification of code blocks in Org-mode making them easier
>>> to learn and use and removing some of the mystery around their syntax.
>>>
>>> What does everyone think?
>>>
>>> Are there suggestions for the best names for each code block entity
>>> (either in the list or not in the list)?
>>>
>>> Are there cases where we want to continue to allow synonyms (e.g., in
>>> named data so that "results" can be used for code block results but
>>> "data" can be used for hand-written data)?
>>>
>>> Thanks -- Eric
>>>
>>> Footnotes: 
>>> [1] named code blocks
>>>
>>> #+source: foo
>>> #+begin_src emacs-lisp
>>>   'foo
>>> #+end_src
>>>
>>> #+srcname: foo
>>> #+begin_src emacs-lisp
>>>   'foo
>>> #+end_src
>>>
>>> #+function: foo
>>> #+begin_src emacs-lisp
>>>   'foo
>>> #+end_src
>>>
>>> [2]  calling external functions
>>>
>>> #+call: foo()
>>>
>>> #+lob: foo()
>>>
>>> [3]  named data
>>>
>>> #+data: something
>>> : something
>>> #+results: something
>>> : something
>>>
>>> etc...
>>
>> named code blocks [1] "source"
>> calling external functions [2] "call"
>> named data [3] "object"
>>
>> My motivation for [3] "object" instead of the suggested alternates is the
>> hope that it will be possible to name things like lists and paragraphs
>> (that aren't results or data) and pass these objects to source code blocks.
>
> I disagree with Tom on [1]: it should clearly be "srcname", in analogy
> to #+tblname - and also so I don't have to change my files :-} (but see my
> question about tblname below).

I have low attraction for "function" as this seems too-programming oriented:
IMHO, it's too much minded toward the "results value" aspect of Babel
("functional mode"), and not at all toward the "scripting mode" (shell
scripts, SQL commands).

Moreover, in fact, in such blocks, we don't have executable code per se: just
think at Ledger transactions that I would want to wrap...

#+srcname: journal
#+begin_src ledger
2008/01/03 * ( ) ME
Assets:Bank:Checking:77045030   550.00 
EUR
Assets:Bank:Transferred

2008/01/01 * ( ) UNKNOWN-PAYEE
Assets:Bank:Checking:7704503021.91 
EUR
Expenses:Unknown
#+end_src

..., and reuse in a block later (through the Noweb expansion):

#+srcname: ledger-balance
#+begin_src ledger :cmdline bal :noweb yes
<>
#+end_src

Though, in this latter case, one could object I could maybe (?) refer them
through the "object" name facility -- I'm referring to point 3 of Tom's
answer, see below.

Note -- Then, I would loose the language-editing facility. When we create
an "object" ("results" or "data"), there is no "language" associated,
hence no ability to edit easily via C-c ', and no correct "native
fontification". In fact, such an object has no delimiter either, so it
would never be a true replacement.

Now, between "srcname" and "source": I'm used to whatever my Yasnippet is
entering for me. That's currently "srcname". I don't have a strong opinion,
though, to choose one over the other, except that I like Nick's argument with
the table analogy.

> I agree on [2] "call".

I clearly agree on "call" as well.

Here, I'd like to ask: what about "sbe"?  In my own understanding, it's a
call, absolutely similar to "call". Is there a technical reason to be forced
to differentiate both?  If no, can we use "call" as well instead of "sbe"?

> I'm confused by [3] so I will say nothing for now, except to ask some
> questions: are we talking about what a human would use to label a piece of
> data for consumption by a block (including perhaps the future possibilities
> of lists and paragraphs that Tom brought up)? what babel would use to label
> a results block (possibly so that it could

Re: [O] [RFC] Standardized code block keywords

[Torsten Wagner]

Hi,

> Ideally if we limit each of the above to only one alternative we could
> simplify the specification of code blocks in Org-mode making them easier
> to learn and use and removing some of the mystery around their syntax.
>
> What does everyone think?

Just to make it as easy as possible for everyone
Might it be possible to introduce a small flags like "obsolete" and
"stable" (standard)
Old functions, old syntax, etc., might move first to obsolete before
completely removed...
We could open an older file and if it isn't working, we could try

#+PROPERTY: babel-function-set obsolete

if it works, we have to modify the code, because obviously the code
requires changed to be compatible in the future. However, just for the
moment it is still working. This would give people more time to change
there code accordingly. As murphy law tells us one will notice that
the particular file is broken exact 5 minutes before the meeting with
your boss standing behind you yelling print it, print it  ;)

I know git would be perfect to keep the code base frozen for a certain
syntax. However, babel is bundled with org-mode which is bundled with
Emacs. Thus, it might be very difficult to tell people they have to
use org-babel from git with the tag [org-babel_XX] if they want to use
there old style files.  AFAIK org-babel does not even come with a own
version numbering, right?

Alternatively, keep the syntax a little bit longer as it is and create
warning messages to point users to future changes (not sure how much
time left for emacs24)
"Warning: #+lob: in line XX is obsolete, please use #+call: in the
future. (manual-link)"

To make is short, is is possible to introduce changes "slowly"

As for voting:
[1]
#+function: would be what I would expect from other programming
languages. Where an unnamed source code block would be something like
a lambda function.
However, "function" as a term is heavily used in many target languages
too. This makes parsing, reading and discussing a bit difficult. ("I
called the function foo", "Wait, do you call the org-mode function
foo, or the python function foo?")
Thus, I vote for #+srcname similar to #+tblname to make sure about the
difference between org-babel and the target languages.

[2]
#+call:, simply because I never can remember "lob" and the acronym is
something difficult for newbies.

[3]
I tend to  #+results: because it fits more to the entire babel syntax.
However, earlier on the mailing list people were pointing out that one
is going to change "results" for a unknown source block (that was the
reason "data" was introduced) and I think this is a valid
argument. Maybe "data" and "results" should be both valid if only to
pleasure human thinking. However, if I understood correctly, maybe
data could be changed to be more some type of constant? That is,
#+data: foo can not be changed by a source code block named foo
(because it isn't a "result" but "data") but only by human (as a
"data" input). Does this make sense?

Totti

Re: [O] [RFC] Standardized code block keywords

[Christian Moe]

I disagree with Tom on [1]: it should clearly be "srcname", in analogy
to #+tblname - and also so I don't have to change my files :-} (but see
my question about tblname below).


I'll have to change my files, either way. The price one pays for 
inconsistency. But as I've recently learned from Carsten, it should be 
a one-liner in Perl. :-)


For the sake of analogy, I'll cast my vote for SRCNAME, even if SOURCE 
is more aesthetically pleasing.




I agree on [2] "call".


+1



I'm confused by [3] so I will say nothing for now, except to ask some
questions: are we talking about what a human would use to label a piece
of data for consumption by a block (including perhaps the future
possibilities of lists and paragraphs that Tom brought up)? what babel
would use to label a results block (possibly so that it could be
consumed by another block in a chain)? both? would that mean
that #+tblname would go the way of the dodo and that tables would be
labelled with #+data (or #+object or whatever else we come up with)?


+1 (Confused, too)

I wasn't even aware of #+DATA. Does it do anything TBLNAME and SRCNAME 
don't?


A reason to keep TBLNAME is that it's also used by the spreadsheet 
remote references. If Babel looked for DATA instead, a table that is 
both a remote reference for another spreadsheet and a data source for 
a src block would need both TBLNAME and DATA, which seems redundant.


As for labeling lists and paragraphs, I recall from the list that 
Nicolas Goaziou is working on a generalized way to set captions, 
labels and attributes for various kinds of Org block, as is possible 
now for tables and images. I thought that sounded promising. I don't 
know if he planned for block names, too (currently we have tblname but 
no imgname), but that could make sense. In which case it might be a 
good idea to coordinate.

Re: [O] [RFC] Standardized code block keywords

[Nick Dokos]

Thomas S. Dye  wrote:

> Eric Schulte  writes:
> 
> >> [1] I have the same "annoying" feelings with #+SOURCE, #+SRCNAME, 
> >> #+FUNCTION,
> >> #+CALL, #+LOB, and SBE, some of which are interchangeable; some
> >> not. I'd prefer
> >> deprecating an old form when a better one is found.
> >
> > This point of view has been raised previously both on the mailing list
> > and in the #org-mode IRC chat room.  I think it is time that we decided
> > as a community what we want to do about the prevalence of code block
> > synonyms -- we should make this decision before the release of Emacs24
> > after which syntax will become harder to change.
> >
> > There are currently a number of instances of synonymous keywords when
> > dealing with code blocks, specifically.
> >
> >  named code blocks [1] -- "source" "srcname" "function"
> > calling external functions [2] -- "call" "lob"
> > named data [3] -- "tblname" "resname" "results" "data"
> >
> > Ideally if we limit each of the above to only one alternative we could
> > simplify the specification of code blocks in Org-mode making them easier
> > to learn and use and removing some of the mystery around their syntax.
> >
> > What does everyone think?
> >
> > Are there suggestions for the best names for each code block entity
> > (either in the list or not in the list)?
> >
> > Are there cases where we want to continue to allow synonyms (e.g., in
> > named data so that "results" can be used for code block results but
> > "data" can be used for hand-written data)?
> >
> > Thanks -- Eric
> >
> > Footnotes: 
> > [1] named code blocks
> >
> > #+source: foo
> > #+begin_src emacs-lisp
> >   'foo
> > #+end_src
> >
> > #+srcname: foo
> > #+begin_src emacs-lisp
> >   'foo
> > #+end_src
> >
> > #+function: foo
> > #+begin_src emacs-lisp
> >   'foo
> > #+end_src
> >
> > [2]  calling external functions
> >
> > #+call: foo()
> >
> > #+lob: foo()
> >
> > [3]  named data
> >
> > #+data: something
> > : something
> > #+results: something
> > : something
> >
> > etc...
> 
> Hi Eric,
> 
> named code blocks [1] "source"
> calling external functions [2] "call"
> named data [3] "object"
> 
> My motivation for [3] "object" instead of the suggested alternates is
> the hope that it will be possible to name things like lists and
> paragraphs (that aren't results or data) and pass these objects to
> source code blocks.
> 

I disagree with Tom on [1]: it should clearly be "srcname", in analogy
to #+tblname - and also so I don't have to change my files :-} (but see
my question about tblname below).

I agree on [2] "call".

I'm confused by [3] so I will say nothing for now, except to ask some
questions: are we talking about what a human would use to label a piece
of data for consumption by a block (including perhaps the future
possibilities of lists and paragraphs that Tom brought up)? what babel
would use to label a results block (possibly so that it could be
consumed by another block in a chain)? both? would that mean
that #+tblname would go the way of the dodo and that tables would be
labelled with #+data (or #+object or whatever else we come up with)?

Thanks,
Nick

Re: [O] [RFC] Standardized code block keywords

[Thomas S. Dye]

Eric Schulte  writes:

>> [1] I have the same "annoying" feelings with #+SOURCE, #+SRCNAME, #+FUNCTION,
>> #+CALL, #+LOB, and SBE, some of which are interchangeable; some
>> not. I'd prefer
>> deprecating an old form when a better one is found.
>
> This point of view has been raised previously both on the mailing list
> and in the #org-mode IRC chat room.  I think it is time that we decided
> as a community what we want to do about the prevalence of code block
> synonyms -- we should make this decision before the release of Emacs24
> after which syntax will become harder to change.
>
> There are currently a number of instances of synonymous keywords when
> dealing with code blocks, specifically.
>
>  named code blocks [1] -- "source" "srcname" "function"
> calling external functions [2] -- "call" "lob"
> named data [3] -- "tblname" "resname" "results" "data"
>
> Ideally if we limit each of the above to only one alternative we could
> simplify the specification of code blocks in Org-mode making them easier
> to learn and use and removing some of the mystery around their syntax.
>
> What does everyone think?
>
> Are there suggestions for the best names for each code block entity
> (either in the list or not in the list)?
>
> Are there cases where we want to continue to allow synonyms (e.g., in
> named data so that "results" can be used for code block results but
> "data" can be used for hand-written data)?
>
> Thanks -- Eric
>
> Footnotes: 
> [1] named code blocks
>
> #+source: foo
> #+begin_src emacs-lisp
>   'foo
> #+end_src
>
> #+srcname: foo
> #+begin_src emacs-lisp
>   'foo
> #+end_src
>
> #+function: foo
> #+begin_src emacs-lisp
>   'foo
> #+end_src
>
> [2]  calling external functions
>
> #+call: foo()
>
> #+lob: foo()
>
> [3]  named data
>
> #+data: something
> : something
> #+results: something
> : something
>
> etc...

Hi Eric,

named code blocks [1] "source"
calling external functions [2] "call"
named data [3] "object"

My motivation for [3] "object" instead of the suggested alternates is
the hope that it will be possible to name things like lists and
paragraphs (that aren't results or data) and pass these objects to
source code blocks.

All the best,
Tom

-- 
Thomas S. Dye
http://www.tsdye.com

[O] [RFC] Standardized code block keywords

[Eric Schulte]

> [1] I have the same "annoying" feelings with #+SOURCE, #+SRCNAME, #+FUNCTION,
> #+CALL, #+LOB, and SBE, some of which are interchangeable; some not. I'd 
> prefer
> deprecating an old form when a better one is found.

This point of view has been raised previously both on the mailing list
and in the #org-mode IRC chat room.  I think it is time that we decided
as a community what we want to do about the prevalence of code block
synonyms -- we should make this decision before the release of Emacs24
after which syntax will become harder to change.

There are currently a number of instances of synonymous keywords when
dealing with code blocks, specifically.

 named code blocks [1] -- "source" "srcname" "function"
calling external functions [2] -- "call" "lob"
named data [3] -- "tblname" "resname" "results" "data"

Ideally if we limit each of the above to only one alternative we could
simplify the specification of code blocks in Org-mode making them easier
to learn and use and removing some of the mystery around their syntax.

What does everyone think?

Are there suggestions for the best names for each code block entity
(either in the list or not in the list)?

Are there cases where we want to continue to allow synonyms (e.g., in
named data so that "results" can be used for code block results but
"data" can be used for hand-written data)?

Thanks -- Eric

Footnotes: 
[1] named code blocks

#+source: foo
#+begin_src emacs-lisp
  'foo
#+end_src

#+srcname: foo
#+begin_src emacs-lisp
  'foo
#+end_src

#+function: foo
#+begin_src emacs-lisp
  'foo
#+end_src

[2]  calling external functions

#+call: foo()

#+lob: foo()

[3]  named data

#+data: something
: something

#+results: something
: something

etc...

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