On Tue, Nov 28, 2017 at 6:16 PM Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

>
> AFAICT, there is no place in the manual that explains what is the
> RESULTS keyword


OK, may be that's the first step :)

and under what circumstances it could be useful to write
> it manually.
>

No, I wasn't suggesting a use case where someone writes the #+RESULTS:
contents manually.

Here's what can happen though:

A user could have this to begin with:

=====
#+BEGIN_SRC emacs-lisp
(message "Hello")
#+END_SRC
#+RESULTS:
: Hello

| some | thing | important |
=====

Then for whatever reason, they choose to delete the RESULTS manually.. and
the blank line after that too!

=====
#+BEGIN_SRC emacs-lisp
(message "Hello")
#+END_SRC
#+RESULTS:
| some | thing | important |
=====

Now C-c C-c in the src block will wipe out the user-entered table!

=====
#+BEGIN_SRC emacs-lisp
(message "Hello")
#+END_SRC
#+RESULTS:
: Hello
=====

That's why I proposed earlier to wrap the Org generated results in
something like #+begin_results/#+end_results.

That way, Org is always sure that what it's deleting/overwriting is not
user-entered data.

The current behavior is risky, or at least should somehow be documented.
-- 

Kaushal Modi