Consistency of src-block header argument combinations

[nnicandro]

In particular, consistency with how results are inserted depending on :async
but also consistency with the meaning of the :results header argument in
emacs-jupyter and for regular org-mode source blocks.

Currently there are differences in how the results of a src-block are formatted
when :async yes is specified vs :async no in the presence of other header
arguments. These differences should be removed so that the results are rendered
consistently in both cases.

The differences originate in the use of org-babel-insert-result (which
handles header arguments) for insertion in the :async no case and an
insertion method specific to emacs-jupyter(which ignores most header
arguments) in the :async yes case. The reason for the custom insertion method
in the :async yes case is to support appending results dynamically to the buffer
as they come in and this needs to take into account:

• Value results (images, latex, html, markdown)
• Output from stdout
  • Appending to a fixed width element (contiguous lines that start with :)
  • Appending to the end of an example block
  • Converting a fixed width element to an example block (when the number of
    lines exceeds org-babel-min-lines-for-block-output)
• Wrapping output and value results in a drawer when needed

The simplest solution would be to avoid going through org-babel-insert-result
in the :async no case and use the same insertion method for both cases.
Then, the only difference between the two would be that :async no blocks
Emacs until the src-block is finished. I used org-babel-insert-result for the
:async no case because I eventually wanted to go through org-mode as
much as possible so that all of the header arguments that function handles
would be supported, even in the :async yes case. But it doesn't seem like
this is possible if we are going to support dynamic result insertion.
Is this the only solution?

If we go the route of using the emacs-jupyter specific insertion method for
both :async yes and :async no, it would make sense to support the majority
of the header arguments of regular org-mode blocks. Below is a list of header
arguments that are currently considered in emacs-jupyter:

• :results raw: Only considered when LaTeX results are returned. Normally
  LaTeX results are wrapped in an export block, when this
  argument is provided, the LaTeX is inserted directly into the
  buffer.
• :results scalar: Normally when text/plain results are returned the result
  is converted into an Org mode table it it look like one. When this
  argument is provided, the table conversion is suppressed.
• :file : Normally when image results are returned, the image data is
  written to a file with a file name based on
  org-babel-jupyter-resource-directory and the image data,
  then a link to that file is inserted into the buffer. If this
  argument is provided, the file name used is <path> instead.

I think it would make sense to also support :result list and :results link
and possibly the :post header argument. But are there others that would make
sense?

Some more questions:

• I think the :file argument has changed in Org 9.2.1 to mean write the
  results to :file. To get the old meaning, in addition to :file, you have
  to specify :results link. This doesn't matter so much since we have a
  custom result insertion method so we can slightly change the meaning of the
  header argument as has already been done. But for the sake of consistency,
  should we keep the semantics of :file the same as org-mode?

• The above point raises the question: When it comes to header arguments,
  should the general strategy be to always defer to the way that org-mode
  handles them? I don't see why we wouldn't.

• Currently output is intermixed with value results by default and the result
  of a code block is only suppressed when :result output is specified.
  Jupyter has the notion of display-data messages which can be considered as
  additional value results that come before the final result of the source
  block. Even in the case of :results output, these additional results are
  not suppressed. Would it make sense to stick with the current behavior and
  have :results value mean both output and value results? I did this because
  a Jupyter notebook would insert both stdout and value results by default.

  Would it make sense then for :results output to mean suppress all value
  results, even those from display-data messages and just have the stdout as
  the result? I think so.

• How would :results list work? Should we just create a list based on stdout
  or the value of the result? Again, Jupyter has the notion of display-data
  messages which act as additional value results.

[nnicandro]

Related issue #31

[nnicandro]

Closing right now since problems related to the slightly different meanings of header arguments that emacs-jupyter has compared to org-mode are not really an issue in practice.

If anyone feels differently, open a new issue or comment on this one and I will re-open.