Two modifications for source blocks processing (will be in 7.9.2)

Two modifications for source blocks processing (will be in 7.9.2)

[Bastien]

Dear all,

this is to advertize two small modifications wrt source blocks
processing.

1) Please use ":results drawer" instead of ":results wrap" to insert
   results like this:

   #+BEGIN_SRC emacs-lisp :results drawer
   (message "a")
   #+END_SRC
   
   #+RESULTS:
   :RESULTS:
   a
   :END:

2) Support for ":results org" has been removed.  You can either
   insert the results with ":results raw" or "results drawer" if
   you need to tell the exporter to include/exclude the results
   (by including/excluding the :RESULTS: drawer from export.)

Those two changes above will be in 7.9.2.

Thanks,

-- 
 Bastien

Re: Two modifications for source blocks processing (will be in 7.9.2)

[Sebastien Vauban]

Hi Bastien,

Bastien wrote:
> this is to advertize two small modifications wrt source blocks
> processing.
>
> 1) Please use ":results drawer" instead of ":results wrap" to insert
>    results like this:
>
>    #+BEGIN_SRC emacs-lisp :results drawer
>    (message "a")
>    #+END_SRC
>    
>    #+RESULTS:
>    :RESULTS:
>    a
>    :END:

OK. That name is clearly better!

> 2) Support for ":results org" has been removed.

Why don't we have anymore "#+begin/end_org" blocks while we still have
"#+begin_html" and "#+begin_LaTeX" blocks?  Org as the language seemed normal
to insert blocks in Org-syntax.

How will Org constructs be supported, for example headlines in the old
"#+begin/end_org" blocks -- with the "," used for protecting the export?

#+begin_src org
,* This is an headline
,This is some text.
#+end_src

>    You can either insert the results with ":results raw" or "results drawer"
>    if you need to tell the exporter to include/exclude the results (by
>    including/excluding the :RESULTS: drawer from export.)

Will ":RESULTS:" drawers be included by default, to mimic the current support
of "#+begin/end_org" blocks?

Best regards,
  Seb

-- 
Sebastien Vauban

Re: Two modifications for source blocks processing (will be in 7.9.2)

[Bastien]

Hi Sébastien,

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

>> 2) Support for ":results org" has been removed.
>
> Why don't we have anymore "#+begin/end_org" blocks while we still have
> "#+begin_html" and "#+begin_LaTeX" blocks?  Org as the language seemed normal
> to insert blocks in Org-syntax.

The only advantage of using #+BEGIN_ORG over a raw insert was to be able
to fold the block.  But that's already available with :results drawer.

Beside, this was the only place were #+BEGIN_ORG was used, and there was
questions on how to let the new exporter process these blocks.

> How will Org constructs be supported, for example headlines in the old
> "#+begin/end_org" blocks -- with the "," used for protecting the export?
>
> #+begin_src org
> ,* This is an headline
> ,This is some text.
> #+end_src

Mhh... yeah.  I've pushed a change, this is what ":results org" will do
now.  I'll ping Eric and Nicolas so that they care review this.

>>    You can either insert the results with ":results raw" or "results drawer"
>>    if you need to tell the exporter to include/exclude the results (by
>>    including/excluding the :RESULTS: drawer from export.)
>
> Will ":RESULTS:" drawers be included by default, to mimic the current support
> of "#+begin/end_org" blocks?

You have ":results org" now.

-- 
 Bastien

Re: Two modifications for source blocks processing (will be in 7.9.2)

[Bastien]

WXHGMQZGWMUF@spammotel.com writes:

> It's almost OK: only the comma is not automatically inserted as line
> prefix[1].

Yes, this has always been like this AFAICT.

-- 
 Bastien

Re: Two modifications for source blocks processing (will be in 7.9.2)

[Nicolas Goaziou]

Hello,

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

> Why don't we have anymore "#+begin/end_org" blocks while we still have
> "#+begin_html" and "#+begin_LaTeX" blocks?  Org as the language seemed normal
> to insert blocks in Org-syntax.

#+begin_latex (like #+begin_html, #+begin_ascii, #+begin_md...) are
"export blocks", which basically means "insert contents as-is in output
from matching export back-end, ignore everything in other back-ends.".

They are relative to export back-ends, not languages. And there's no Org
back-end so far. So, they do not make much sense for now.

On the other hand, when you want to write in a foreign language, you use
#+begin_src blocks.

> Will ":RESULTS:" drawers be included by default, to mimic the current support
> of "#+begin/end_org" blocks?

In the new export engine, every drawer (excepted property drawer) is
included by default.


Regards,

-- 
Nicolas Goaziou

Re: Two modifications for source blocks processing (will be in 7.9.2)

[Thomas S. Dye]

Hi Seb,

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

> Hi Bastien,
>
> Bastien wrote:
>> this is to advertize two small modifications wrt source blocks
>> processing.
>>
>> 1) Please use ":results drawer" instead of ":results wrap" to insert
>>    results like this:
>>
>>    #+BEGIN_SRC emacs-lisp :results drawer
>>    (message "a")
>>    #+END_SRC
>>    
>>    #+RESULTS:
>>    :RESULTS:
>>    a
>>    :END:
>
> OK. That name is clearly better!
>
>> 2) Support for ":results org" has been removed.
>
> Why don't we have anymore "#+begin/end_org" blocks while we still have
> "#+begin_html" and "#+begin_LaTeX" blocks?  Org as the language seemed normal
> to insert blocks in Org-syntax.
>
> How will Org constructs be supported, for example headlines in the old
> "#+begin/end_org" blocks -- with the "," used for protecting the export?
>
> #+begin_src org
> ,* This is an headline
> ,This is some text.
> #+end_src
>
>>    You can either insert the results with ":results raw" or "results drawer"
>>    if you need to tell the exporter to include/exclude the results (by
>>    including/excluding the :RESULTS: drawer from export.)
>
> Will ":RESULTS:" drawers be included by default, to mimic the current support
> of "#+begin/end_org" blocks?
>
> Best regards,
>   Seb

:results org was a synonym for :results raw, so I think "small change"
here probably means that support for the synonym was dropped.

#+begin/end_org blocks should still work with the :wrap header argument,
 which hasn't been altered, IIUC.

All the best,
Tom

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

Re: Two modifications for source blocks processing (will be in 7.9.2)

[Sebastien Vauban]

Hi Thomas,

A (very) quick answer...

Thomas S. Dye wrote:
> Sebastien Vauban writes:
>> Bastien wrote:
>>> this is to advertize two small modifications wrt source blocks
>>> processing.
>>>
>>> 1) Please use ":results drawer" instead of ":results wrap" to insert
>>>    results like this:
>>>
>>>    #+BEGIN_SRC emacs-lisp :results drawer
>>>    (message "a")
>>>    #+END_SRC
>>>    
>>>    #+RESULTS:
>>>    :RESULTS:
>>>    a
>>>    :END:
>>
>> OK. That name is clearly better!
>>
>>> 2) Support for ":results org" has been removed.
>>
>> Why don't we have anymore "#+begin/end_org" blocks while we still have
>> "#+begin_html" and "#+begin_LaTeX" blocks?  Org as the language seemed normal
>> to insert blocks in Org-syntax.
>>
>> How will Org constructs be supported, for example headlines in the old
>> "#+begin/end_org" blocks -- with the "," used for protecting the export?
>>
>> #+begin_src org
>> ,* This is an headline
>> ,This is some text.
>> #+end_src
>>
>>>    You can either insert the results with ":results raw" or "results drawer"
>>>    if you need to tell the exporter to include/exclude the results (by
>>>    including/excluding the :RESULTS: drawer from export.)
>>
>> Will ":RESULTS:" drawers be included by default, to mimic the current support
>> of "#+begin/end_org" blocks?
>
> :results org was a synonym for :results raw

No!

With :results raw, the raw output is inserted directly into the Org mode
buffer. This is a good option if your code block will output *Org mode
formatted text* (this will even be fontified as Org text you would have typed
yourself).

As there are *no obvious markers to delimit the results* in the Org mode file,
there is no way to know where raw results begin or end: raw results *cannot be
removed* from the buffer.

With :results org, raw Org mode results will be harmlessly *wrapped in a Org
mode block*. The "#+begin/end_org" block wrapper makes it possible for the
entirety of the results to be clearly located and replaced upon code block
re-evaluation.

> so I think "small change" here probably means that support for the synonym
> was dropped.

Hence, not a synonym.

> #+begin/end_org blocks should still work with the :wrap header argument,
>  which hasn't been altered, IIUC.

No. AFAICT:

- "wrap" will disappear (renamed as "drawer"),

- "drawer" is not the same as the old "org" option (as the results gets
  inserted into a drawer, not into a block).

Best regards,
  Seb

-- 
Sebastien Vauban

Re: Two modifications for source blocks processing (will be in 7.9.2)

[Thomas S. Dye]

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

> Hi Thomas,
>
> A (very) quick answer...
>
> Thomas S. Dye wrote:
>> Sebastien Vauban writes:
>>> Bastien wrote:
>>>> this is to advertize two small modifications wrt source blocks
>>>> processing.
>>>>
>>>> 1) Please use ":results drawer" instead of ":results wrap" to insert
>>>>    results like this:
>>>>
>>>>    #+BEGIN_SRC emacs-lisp :results drawer
>>>>    (message "a")
>>>>    #+END_SRC
>>>>    
>>>>    #+RESULTS:
>>>>    :RESULTS:
>>>>    a
>>>>    :END:
>>>
>>> OK. That name is clearly better!
>>>
>>>> 2) Support for ":results org" has been removed.
>>>
>>> Why don't we have anymore "#+begin/end_org" blocks while we still have
>>> "#+begin_html" and "#+begin_LaTeX" blocks?  Org as the language seemed normal
>>> to insert blocks in Org-syntax.
>>>
>>> How will Org constructs be supported, for example headlines in the old
>>> "#+begin/end_org" blocks -- with the "," used for protecting the export?
>>>
>>> #+begin_src org
>>> ,* This is an headline
>>> ,This is some text.
>>> #+end_src
>>>
>>>>    You can either insert the results with ":results raw" or "results drawer"
>>>>    if you need to tell the exporter to include/exclude the results (by
>>>>    including/excluding the :RESULTS: drawer from export.)
>>>
>>> Will ":RESULTS:" drawers be included by default, to mimic the current support
>>> of "#+begin/end_org" blocks?
>>
>> :results org was a synonym for :results raw
>
> No!
>
> With :results raw, the raw output is inserted directly into the Org mode
> buffer. This is a good option if your code block will output *Org mode
> formatted text* (this will even be fontified as Org text you would have typed
> yourself).
>
> As there are *no obvious markers to delimit the results* in the Org mode file,
> there is no way to know where raw results begin or end: raw results *cannot be
> removed* from the buffer.
>
> With :results org, raw Org mode results will be harmlessly *wrapped in a Org
> mode block*. The "#+begin/end_org" block wrapper makes it possible for the
> entirety of the results to be clearly located and replaced upon code block
> re-evaluation.
>
>> so I think "small change" here probably means that support for the synonym
>> was dropped.
>
> Hence, not a synonym.
>

Sorry.  I must have looked at an old version of the manual.

>> #+begin/end_org blocks should still work with the :wrap header argument,
>>  which hasn't been altered, IIUC.
>
> No. AFAICT:
>
> - "wrap" will disappear (renamed as "drawer"),
>
> - "drawer" is not the same as the old "org" option (as the results gets
>   inserted into a drawer, not into a block).

Isn't it ":results wrap" that has disappeared?  Will ":wrap org" also
disappear?  Or, am I hopelessly confused?

All the best,
Tom

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

Re: Two modifications for source blocks processing (will be in 7.9.2)

[Eric Schulte]

> - "drawer" is not the same as the old "org" option (as the results gets
>   inserted into a drawer, not into a block).
>

And the difference here between an org block and a drawer is that the
contents of the drawer can not be exported?

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

Re: Two modifications for source blocks processing (will be in 7.9.2)

[Bastien]

Hi Sébastien,

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

> With :results org, raw Org mode results will be harmlessly *wrapped in a Org
> mode block*. The "#+begin/end_org" block wrapper makes it possible for the
> entirety of the results to be clearly located and replaced upon code block
> re-evaluation.

So from now on, you'll enjoy all this with #+BEGIN_SRC org instead of
#+BEGIN_ORG.

> - "wrap" will disappear (renamed as "drawer"),

It *has* been deprecated.  Meaning that you can still use "wrap" and get
the same results than with "drawer", but it is not documented.  It will 
surely be removed for Org 8.0.

> - "drawer" is not the same as the old "org" option (as the results gets
>   inserted into a drawer, not into a block).

Confirmed.  "Drawer" means... use a drawer.  And Org means use an Org
source block.  The only thing that has been removed is the notion of an
"Org block", which was not clear enough (see Nicolas explanations in
this thread.)

-- 
 Bastien

Re: Two modifications for source blocks processing (will be in 7.9.2)

[Thomas S. Dye]

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

> Hi Thomas,
>
> A (very) quick answer...
>
> Thomas S. Dye wrote:
>> Sebastien Vauban writes:
>>> Bastien wrote:
>>>> this is to advertize two small modifications wrt source blocks
>>>> processing.
>>>>
>>>> 1) Please use ":results drawer" instead of ":results wrap" to insert
>>>>    results like this:
>>>>
>>>>    #+BEGIN_SRC emacs-lisp :results drawer
>>>>    (message "a")
>>>>    #+END_SRC
>>>>    
>>>>    #+RESULTS:
>>>>    :RESULTS:
>>>>    a
>>>>    :END:
>>>
>>> OK. That name is clearly better!
>>>
>>>> 2) Support for ":results org" has been removed.
>>>
>>> Why don't we have anymore "#+begin/end_org" blocks while we still have
>>> "#+begin_html" and "#+begin_LaTeX" blocks?  Org as the language seemed normal
>>> to insert blocks in Org-syntax.
>>>
>>> How will Org constructs be supported, for example headlines in the old
>>> "#+begin/end_org" blocks -- with the "," used for protecting the export?
>>>
>>> #+begin_src org
>>> ,* This is an headline
>>> ,This is some text.
>>> #+end_src
>>>
>>>>    You can either insert the results with ":results raw" or "results drawer"
>>>>    if you need to tell the exporter to include/exclude the results (by
>>>>    including/excluding the :RESULTS: drawer from export.)
>>>
>>> Will ":RESULTS:" drawers be included by default, to mimic the current support
>>> of "#+begin/end_org" blocks?
>>
>> :results org was a synonym for :results raw
>
> No!
>
> With :results raw, the raw output is inserted directly into the Org mode
> buffer. This is a good option if your code block will output *Org mode
> formatted text* (this will even be fontified as Org text you would have typed
> yourself).
>
> As there are *no obvious markers to delimit the results* in the Org mode file,
> there is no way to know where raw results begin or end: raw results *cannot be
> removed* from the buffer.
>
> With :results org, raw Org mode results will be harmlessly *wrapped in a Org
> mode block*. The "#+begin/end_org" block wrapper makes it possible for the
> entirety of the results to be clearly located and replaced upon code block
> re-evaluation.
>
>> so I think "small change" here probably means that support for the synonym
>> was dropped.
>
> Hence, not a synonym.
>
>> #+begin/end_org blocks should still work with the :wrap header argument,
>>  which hasn't been altered, IIUC.
>
> No. AFAICT:
>
> - "wrap" will disappear (renamed as "drawer"),
>
> - "drawer" is not the same as the old "org" option (as the results gets
>   inserted into a drawer, not into a block).
>
> Best regards,
>   Seb

Thanks Seb,

I appreciate your help and patience as I worked out the implications of
the changes.  I think I've got it straight now :)

All the best,
Tom

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

Re: Two modifications for source blocks processing (will be in 7.9.2)

[Achim Gratz]

Bastien writes:
>    #+BEGIN_SRC emacs-lisp :results drawer
>    (message "a")
>    #+END_SRC
>    
>    #+RESULTS:
>    :RESULTS:
>    a
>    :END:

What's the purpose of the #+RESULTS, why not just specify ":results
:DRAWERNAME:"?


Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

Wavetables for the Waldorf Blofeld:
http://Synth.Stromeko.net/Downloads.html#BlofeldUserWavetables

Re: Two modifications for source blocks processing (will be in 7.9.2)

[Bastien]

Hi Achim,

Achim Gratz <Stromeko@nexgo.de> writes:

> What's the purpose of the #+RESULTS, 

#+RESULTS is here whatever the output format is.  It indicates that the
text below has been produced dynamically by the source block above.

> why not just specify ":results :DRAWERNAME:"?

That's an idea -- but :RESULTS: is fine and I don't see added value in
being able to change this drawer's name.

-- 
 Bastien