Syntax of Org Babel results

Syntax of Org Babel results

[Sebastien Vauban]

Hello,

Before Org 8 is out, I'm willing to put light on some last syntax which I find
counter-intuitive and not along the lines of the rest: it concerns the
`results' parameter.

Let's sum up first the list of all parameters:

1. Collection

   - :results value
   - :results output

2. Type of results (when :results is set to `value'):

   - Result types

     + :results vector
     + :results scalar
     + :results list
     + :results file

   - Result wrappers

     + :results raw
     + :results drawer
     + :results org (removed, right?)
     + :results html
     + :results code
     + :results latex
     + :results pp

3. Handling

   - :results replace
   - :results silent
   - :results none
   - :results append
   - :results prepend

As you see (by the shown structure), the different values answer different
questions:

- How the results should be collected from the source code block?
- How they will be inserted into the Org mode buffer?
- How to interpret/wrap the results?
- How the results should be handled?

And answering many of these questions at the same time means giving a
*multi-value* to the parameter, such as:

  :results list append

Wouldn't it make more sense (and be more easily parsed by the machine and be
cleaner and less error-prone for us, poor humans) if `results' would be split
in different parameters for the different questions they answer, each of those
parameters getting at most one value?

Something along the lines of:

  :results_type file :results_insertion append

  (those names may be ugly, it just for the purpose of explaining my idea).

I know that it's the ultimate moment to discuss such a change, would there be
consensus, before Org 8 is out.

Best regards,
  Seb

-- 
Sebastien Vauban

Re: Syntax of Org Babel ":results" header argument

[Sebastien Vauban]

Hello,

As there was no reaction to this, I'd like to bump it up. At least, to either
have a discussion on this, or a clearly stated "no go".

Best regards,
Seb

"Sebastien Vauban" wrote:
> Before Org 8 is out, I'm willing to put light on some last syntax which I find
> counter-intuitive and not along the lines of the rest: it concerns the
> `results' parameter.
>
> Let's sum up first the list of all parameters:
>
> 1. Collection
>
>    - :results value
>    - :results output
>
> 2. Type of results (when :results is set to `value'):
>
>    - Result types
>
>      + :results vector
>      + :results scalar
>      + :results list
>      + :results file
>
>    - Result wrappers
>
>      + :results raw
>      + :results drawer
>      + :results org (removed, right?)
>      + :results html
>      + :results code
>      + :results latex
>      + :results pp
>
> 3. Handling
>
>    - :results replace
>    - :results silent
>    - :results none
>    - :results append
>    - :results prepend
>
> As you see (by the shown structure), the different values answer different
> questions:
>
> - How the results should be collected from the source code block?
> - How they will be inserted into the Org mode buffer?
> - How to interpret/wrap the results?
> - How the results should be handled?
>
> And answering many of these questions at the same time means giving a
> *multi-value* to the parameter, such as:
>
>   :results list append
>
> Wouldn't it make more sense (and be more easily parsed by the machine and be
> cleaner and less error-prone for us, poor humans) if `results' would be split
> in different parameters for the different questions they answer, each of those
> parameters getting at most one value?
>
> Something along the lines of:
>
>   :results_type file :results_insertion append
>
>   (those names may be ugly, it just for the purpose of explaining my idea).
>
> I know that it's the ultimate moment to discuss such a change, would there be
> consensus, before Org 8 is out.

-- 
Sebastien Vauban

Re: Syntax of Org Babel ":results" header argument

[Eric S Fraga]

Sebastien Vauban <wxhgmqzgwmuf@spammotel.com> writes:

> Hello,
>
> As there was no reaction to this, I'd like to bump it up. At least, to either
> have a discussion on this, or a clearly stated "no go".

Okay, if nobody else answers, here I go!  I am happy with the current
approach as it's easier for me to see, at a glance, what is intended to
happen with the results and a single word key is easier to type.

However, I would not be distraught if a change were made along the lines
you propose.

-- 
: Eric S Fraga, GnuPG: 0xC89193D8FFFCF67D
: in Emacs 24.3.50.1 and Org release_8.0-pre-72-gc66641

Re: Syntax of Org Babel ":results" header argument

[shripad sinari]

[-- Attachment #1: Type: text/plain, Size: 808 bytes --]

I think Sebastian's suggestions are very nice and would be very helpful.

Shripad
Tucson, AZ


On Fri, Mar 15, 2013 at 4:41 AM, Eric S Fraga <e.fraga@ucl.ac.uk> wrote:

> Sebastien Vauban <wxhgmqzgwmuf@spammotel.com> writes:
>
> > Hello,
> >
> > As there was no reaction to this, I'd like to bump it up. At least, to
> either
> > have a discussion on this, or a clearly stated "no go".
>
> Okay, if nobody else answers, here I go!  I am happy with the current
> approach as it's easier for me to see, at a glance, what is intended to
> happen with the results and a single word key is easier to type.
>
> However, I would not be distraught if a change were made along the lines
> you propose.
>
> --
> : Eric S Fraga, GnuPG: 0xC89193D8FFFCF67D
> : in Emacs 24.3.50.1 and Org release_8.0-pre-72-gc66641
>
>
>

[-- Attachment #2: Type: text/html, Size: 1393 bytes --]

Re: Syntax of Org Babel ":results" header argument

[Jay Kerns]

Greetings,

On Fri, Mar 15, 2013 at 1:30 PM, shripad sinari
<shripad.sinari@gmail.com> wrote:

[snip]

I am happy with the current behavior, but
that isn't to say it couldn't possibly be improved or that I
disagree with Sebastien's suggestions.  It did take me quite some
time to figure out what the heck was going on with it all, but
now that I know, I like it a lot.

Few comments:

- :results graphics makes the list even longer, yes?  :-) I'm not
  sure that every language supports it and I don't believe it's
  currently in the manual. And I don't think it directly affects
  what Sebastien is asking about.

- Out of the myriad combinations, I only use a few regularly.

- I hope that a change, if any, would be mindful of
  brevity. Particularly with inline src blocks, it is much
  shorter to write

  : SRC_foo[:results value scalar raw append]{blah}

  than it is to write

  : SRC_foo[:results_collect value :results_type scalar
:results_handling append :results_wrapper raw]{blah}

  (or however it would be decided to handle that).

-- 
Jay

Re: Syntax of Org Babel ":results" header argument

[Bastien]

Hi Sébastien,

"Sebastien Vauban"
<wxhgmqzgwmuf-geNee64TY+gS+FvcfC7Uqw@public.gmane.org> writes:

> As there was no reaction to this, I'd like to bump it up. At least, to either
> have a discussion on this, or a clearly stated "no go".

I tend to agree with Jay here and I prefer the minimalist syntax,
although values for the :results parameter are heterogeneous.

Also, I think the change you proposal can be backward-compatible,
and in that case, making it after 8.0 is fine.

In any case, I'll let Eric and Nicolas advice have priority over
mine here.

Best,

-- 
 Bastien

Re: Syntax of Org Babel ":results" header argument

[Eric Schulte]

Bastien <bzg@altern.org> writes:

> Hi Sébastien,
>
> "Sebastien Vauban"
> <wxhgmqzgwmuf-geNee64TY+gS+FvcfC7Uqw@public.gmane.org> writes:
>
>> As there was no reaction to this, I'd like to bump it up. At least, to either
>> have a discussion on this, or a clearly stated "no go".
>
> I tend to agree with Jay here and I prefer the minimalist syntax,
> although values for the :results parameter are heterogeneous.
>

+1 for maintaining the existing concise syntax.

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

Re: Syntax of Org Babel ":results" header argument

[Thomas S. Dye]

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

> Bastien <bzg@altern.org> writes:
>
>> Hi Sébastien,
>>
>> "Sebastien Vauban"
>> <wxhgmqzgwmuf-geNee64TY+gS+FvcfC7Uqw@public.gmane.org> writes:
>>
>>> As there was no reaction to this, I'd like to bump it up. At least, to either
>>> have a discussion on this, or a clearly stated "no go".
>>
>> I tend to agree with Jay here and I prefer the minimalist syntax,
>> although values for the :results parameter are heterogeneous.
>>
>
> +1 for maintaining the existing concise syntax.

+1 for stable syntax.

Tom

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

Re: Syntax of Org Babel ":results" header argument

[Andreas Leha]

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

> Eric Schulte <schulte.eric@gmail.com> writes:
>
>> Bastien <bzg@altern.org> writes:
>>
>>> Hi Sébastien,
>>>
>>> "Sebastien Vauban"
>>> <wxhgmqzgwmuf@spammotel.com> writes:
>>>
>>>> As there was no reaction to this, I'd like to bump it up. At least, to either
>>>> have a discussion on this, or a clearly stated "no go".
>>>
>>> I tend to agree with Jay here and I prefer the minimalist syntax,
>>> although values for the :results parameter are heterogeneous.
>>>
>>
>> +1 for maintaining the existing concise syntax.
>
> +1 for stable syntax.
>

+1 one more vote

Andreas

Re: Syntax of Org Babel ":results" header argument

[Sebastien Vauban]

Hello all,

Andreas Leha wrote:
> tsd-P0awH739Ni4AvxtiuMwx3w@public.gmane.org (Thomas S. Dye) writes:
>> Eric Schulte <schulte.eric-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> writes:
>>> Bastien <bzg-whniv8GeeGkdnm+yROfE0A@public.gmane.org> writes:
>>>> "Sebastien Vauban" writes:
>>>>
>>>>> As there was no reaction to this, I'd like to bump it up. At least, to either
>>>>> have a discussion on this, or a clearly stated "no go".
>>>>
>>>> I tend to agree with Jay here and I prefer the minimalist syntax,
>>>> although values for the :results parameter are heterogeneous.
>>>
>>> +1 for maintaining the existing concise syntax.
>>
>> +1 for stable syntax.
>
> +1 one more vote

I've got the authoritative answers I was expecting. It was just a RFI. Case is
closed!

Best regards,
  Seb

-- 
Sebastien Vauban