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 nicholas.do...@hp.com writes:
  Eric Schulte schulte.e...@gmail.com 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

[Eric Schulte]

Daniel Bausch danielbau...@gmx.de 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

[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 schulte.e...@gmail.com
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 

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 schulte.e...@gmail.com
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=.  If 

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

[Nick Dokos]

Eric Schulte schulte.e...@gmail.com 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]

Nick Dokos nicholas.do...@hp.com writes:

 Eric Schulte schulte.e...@gmail.com 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 schulte.e...@gmail.com
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 

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 nicholas.do...@hp.com 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

[Nick Dokos]

Thomas S. Dye t...@tsdye.com 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 nicholas.do...@hp.com 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]

Daniel Bausch danielbau...@gmx.de 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

[Eric Schulte]

Daniel Bausch danielbau...@gmx.de 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

[Giovanni Ridolfi]

Nick Dokos nicholas.do...@hp.com writes:

 Eric Schulte schulte.e...@gmail.com 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

[Daniel Bausch]

Am Mittwoch 26 Oktober 2011, 15:10:03 schrieb Giovanni Ridolfi:
 Nick Dokos nicholas.do...@hp.com writes:
  Eric Schulte schulte.e...@gmail.com 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

[Nick Dokos]

Daniel Bausch danielbau...@gmx.de wrote:

 Am Mittwoch 26 Oktober 2011, 15:10:03 schrieb Giovanni Ridolfi:
  Nick Dokos nicholas.do...@hp.com writes:
   Eric Schulte schulte.e...@gmail.com 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]

  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

[Rainer M Krug]

On Fri, Oct 21, 2011 at 6:24 PM, Eric Schulte schulte.e...@gmail.comwrote:

  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), MSc (Conservation Biology,
UCT), Dipl. Phys. (Germany)

Centre of Excellence for Invasion Biology
Stellenbosch University
South Africa

Tel :   +33 - (0)9 53 10 27 44

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

[Rainer M Krug]

On Tue, Oct 25, 2011 at 8:52 AM, Rainer M Krug r.m.k...@gmail.com 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 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 

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

[Daniel Bausch]

Am Dienstag 25 Oktober 2011, 03:30:46 schrieb Eric Schulte:
 Sebastien Vauban wxhgmqzgw...@spammotel.com 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

[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

[Sebastien Vauban]

Hi Daniel,

Daniel Bausch wrote:
 Am Dienstag 25 Oktober 2011, 03:30:46 schrieb Eric Schulte:
 Sebastien Vauban wxhgmqzgw...@spammotel.com 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

[Sebastien Vauban]

Hi Rainer,

Rainer M Krug wrote:
 On Fri, Oct 21, 2011 at 6:24 PM, Eric Schulte schulte.e...@gmail.comwrote:
 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

[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

[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

[Nick Dokos]

Eric Schulte schulte.e...@gmail.com 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

[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

[Martyn Jago]

Nick Dokos nicholas.do...@hp.com writes:

 Eric Schulte schulte.e...@gmail.com 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]

Martyn Jago martyn.j...@btinternet.com writes:

 Nick Dokos nicholas.do...@hp.com writes:

 Eric Schulte schulte.e...@gmail.com 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

[Nick Dokos]

Eric Schulte schulte.e...@gmail.com wrote:

 Martyn Jago martyn.j...@btinternet.com writes:
 
  Nick Dokos nicholas.do...@hp.com writes:
 
  Eric Schulte schulte.e...@gmail.com 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

[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

[Daniel Bausch]

Am Dienstag 25 Oktober 2011, 19:21:22 schrieb Nick Dokos:
 Eric Schulte schulte.e...@gmail.com wrote:
  Martyn Jago martyn.j...@btinternet.com writes:
   Nick Dokos nicholas.do...@hp.com writes:
   Eric Schulte schulte.e...@gmail.com 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

[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

[Eric S Fraga]

Daniel Bausch danielbau...@gmx.de 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

[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 e.fr...@ucl.ac.uk wrote:
 
 Daniel Bausch danielbau...@gmx.de 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 Schulte]

Sebastien Vauban wxhgmqzgw...@spammotel.com 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

[Daniel Bausch]

Am Freitag, 21. Oktober 2011, 21:10:27 schrieb Thomas S. Dye:
 Eric Schulte schulte.e...@gmail.com 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

[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

[Thomas S. Dye]

Daniel Bausch danielbau...@gmx.de writes:

 Am Freitag, 21. Oktober 2011, 21:10:27 schrieb Thomas S. Dye:
 Eric Schulte schulte.e...@gmail.com 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
 :  source block
 : #+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

[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

[Daniel Bausch]

Am Sonntag 23 Oktober 2011, 18:09:01 schrieben Sie:
 Daniel Bausch danielbau...@gmx.de writes:
  Am Freitag, 21. Oktober 2011, 21:10:27 schrieb Thomas S. Dye:
  Eric Schulte schulte.e...@gmail.com 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
  : 
  :  source block
  : 
  : #+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-attach-captions-and-attributes target-alist))
   ;; Mark lists with properties
+
   (org-export-mark-list-properties)
 
   ;; Handle source code snippets
@@ -1213,11 +1221,6 @@ on this 

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

[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

[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

[Sebastien Vauban]

Hi Nick, Tom, Eric and all,

Nick Dokos wrote:
 Thomas S. Dye t...@tsdye.com wrote:
 Eric Schulte schulte.e...@gmail.com 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
journal
#+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 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 

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

[Nicolas Goaziou]

Hello,

Eric Schulte schulte.e...@gmail.com 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

[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

[Eric Schulte]

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

 Eric Schulte schulte.e...@gmail.com 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'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]

Nicolas Goaziou n.goaz...@gmail.com writes:

 Hello,

 Eric Schulte schulte.e...@gmail.com 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]

 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

[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 with the code).

I repeat myself, but thanks, once again, for tackling this naming problem.

Best regards,
  Seb

-- 
Sebastien Vauban

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]

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

[Thomas S. Dye]

Eric Schulte schulte.e...@gmail.com writes:

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

 Eric Schulte schulte.e...@gmail.com 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]

 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

[Thorsten]

Hi Eric,

Eric Schulte schulte.e...@gmail.com 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

[Thomas S. Dye]

Eric Schulte schulte.e...@gmail.com 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

[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

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

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

[Thomas S. Dye]

Eric Schulte schulte.e...@gmail.com 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

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

[Nick Dokos]

Thomas S. Dye t...@tsdye.com wrote:

 Eric Schulte schulte.e...@gmail.com 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