Re: [RFC] Standardized code block keywords

[tsd@tsdye.com (Thomas S. Dye)]

Eric Schulte <schulte.eric@gmail.com> writes:

> tsd@tsdye.com (Thomas S. Dye) writes:
>
>> Eric Schulte <schulte.eric@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