emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: Matt Huszagh <huszaghmatt@gmail.com>
To: Emacs-Orgmode <emacs-orgmode@gnu.org>
Subject: [PATCH] Remove additional newline at end of results block
Date: Thu, 30 Dec 2021 07:25:52 -0800	[thread overview]
Message-ID: <CA+X8ke4K0N5fS8Ukr+4kX0aPOv+63eoU3naARMY8DfYTTez_TA@mail.gmail.com> (raw)

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

Inserting this newline prevents a valid use-case and protects against
an edge-case that is completely avoidable without the additional
guarantee it provides. The original intention for inserting the
newline was to avoid the edge case in which a user does not insert a
newline between a source block and the subsequent text and the
subsequent text is merged with the results.

However, there are valid cases in which a user would not want a
newline between a results block and the subsequent buffer text. For
example, many display equations in LaTeX are considered as part of the
surrounding paragraph. Additionally, it is possible to setup a LaTeX
source block to be executable and insert results into the org
buffer. Consider the following example:

some org file (leading colons to prevent git ignoring lines starting
with #):
```
: We can write the simplest equation as
: #+begin_src latex
: \begin{equation}
:   1 + 1 = 2,
: \end{equation}
: #+end_src
: and hope that no one is confused by this.
```

We might then execute this source block to generate some output. For
example, this might generate and SVG image of the block and insert it
into the buffer. That should result in something like

```
: We can write the simplest equation as
: #+begin_src latex
: \begin{equation}
:   1 + 1 = 2,
: \end{equation}
: #+end_src

: #+RESULTS:
: #+begin_results
: [[file:some/file.svg]]
: #+end_results
: and hope that no one is confused by this.
```

When formatted this way, the resulting tex
file (org-latex-export-to-latex) will be:

```
We can write the simplest equation as
\begin{equation}
  1 + 1 = 2,
\end{equation}
and hope that no one is confused by this.
```

which will render correctly. Specifically, the display math
environment will not start a new paragraph after the leading "as" and
a new paragraph will not start between the end of the math display and
the trailing "and".

However, the current behavior results in

```
: We can write the simplest equation as
: #+begin_src latex
: \begin{equation}
:   1 + 1 = 2,
: \end{equation}
: #+end_src

: #+RESULTS:
: #+begin_results
: [[file:some/file.svg]]
: #+end_results

: and hope that no one is confused by this.
```

This blank line necessarily starts a new paragraph in TeX.

Finally, as previously stated, it is entirely possible to control
whether there is a newline between the results block and subsequent
text by leaving a newline between the source block and text. For
example,

```
: We can write the simplest equation as
: #+begin_src latex
: \begin{equation}
:   1 + 1 = 2,
: \end{equation}
: #+end_src

: and hope that no one is confused by this.
```

would still result in

```
: We can write the simplest equation as
: #+begin_src latex
: \begin{equation}
:   1 + 1 = 2,
: \end{equation}
: #+end_src

: #+RESULTS:
: #+begin_results
: [[file:some/file.svg]]
: #+end_results

: and hope that no one is confused by this.
```

[-- Attachment #2: 0001-lisp-ob-core.el-Remove-additional-newline-at-end-of-.patch --]
[-- Type: text/x-patch, Size: 4138 bytes --]

From 667ba67570361bad878c74afdebe068b7916a1bb Mon Sep 17 00:00:00 2001
From: Matt Huszagh <huszaghmatt@gmail.com>
Date: Thu, 30 Dec 2021 06:54:24 -0800
Subject: [PATCH] lisp/ob-core.el: Remove additional newline at end of results

* lisp/ob-core.el (org-babel--insert-results-keyword): Remove newline
at end of results block.

Inserting this newline prevents a valid use-case and protects against
an edge-case that is completely avoidable without the additional
guarantee it provides. The original intention for inserting the
newline was to avoid the edge case in which a user does not insert a
newline between a source block and the subsequent text and the
subsequent text is merged with the results.

However, there are valid cases in which a user would not want a
newline between a results block and the subsequent buffer text. For
example, many display equations in LaTeX are considered as part of the
surrounding paragraph. Additionally, it is possible to setup a LaTeX
source block to be executable and insert results into the org
buffer. Consider the following example:

some org file (leading colons to prevent git ignoring lines starting
with #):
```
: We can write the simplest equation as
: #+begin_src latex
: \begin{equation}
:   1 + 1 = 2,
: \end{equation}
: #+end_src
: and hope that no one is confused by this.
```

We might then execute this source block to generate some output. For
example, this might generate and SVG image of the block and insert it
into the buffer. That should result in something like

```
: We can write the simplest equation as
: #+begin_src latex
: \begin{equation}
:   1 + 1 = 2,
: \end{equation}
: #+end_src

: #+RESULTS:
: #+begin_results
: [[file:some/file.svg]]
: #+end_results
: and hope that no one is confused by this.
```

When formatted this way, the resulting tex
file (org-latex-export-to-latex) will be:

```
We can write the simplest equation as
\begin{equation}
  1 + 1 = 2,
\end{equation}
and hope that no one is confused by this.
```

which will render correctly. Specifically, the display math
environment will not start a new paragraph after the leading "as" and
a new paragraph will not start between the end of the math display and
the trailing "and".

However, the current behavior results in

```
: We can write the simplest equation as
: #+begin_src latex
: \begin{equation}
:   1 + 1 = 2,
: \end{equation}
: #+end_src

: #+RESULTS:
: #+begin_results
: [[file:some/file.svg]]
: #+end_results

: and hope that no one is confused by this.
```

This blank line necessarily starts a new paragraph in TeX.

Finally, as previously stated, it is entirely possible to control
whether there is a newline between the results block and subsequent
text by leaving a newline between the source block and text. For
example,

```
: We can write the simplest equation as
: #+begin_src latex
: \begin{equation}
:   1 + 1 = 2,
: \end{equation}
: #+end_src

: and hope that no one is confused by this.
```

would still result in

```
: We can write the simplest equation as
: #+begin_src latex
: \begin{equation}
:   1 + 1 = 2,
: \end{equation}
: #+end_src

: #+RESULTS:
: #+begin_results
: [[file:some/file.svg]]
: #+end_results

: and hope that no one is confused by this.
```
---
 lisp/ob-core.el | 11 +++--------
 1 file changed, 3 insertions(+), 8 deletions(-)

diff --git a/lisp/ob-core.el b/lisp/ob-core.el
index 7a9467b0e..c0cb283bd 100644
--- a/lisp/ob-core.el
+++ b/lisp/ob-core.el
@@ -1994,14 +1994,9 @@ the results hash, or nil.  Leave point before the keyword."
 		  ":"
 		  (when name (concat " " name))
 		  "\n"))
-  ;; Make sure results are going to be followed by at least one blank
-  ;; line so they do not get merged with the next element, e.g.,
-  ;;
-  ;;   #+results:
-  ;;   : 1
-  ;;
-  ;;   : fixed-width area, unrelated to the above.
-  (unless (looking-at "^[ \t]*$") (save-excursion (insert "\n")))
+  ;; We deliberately do not insert a newline here since there are
+  ;; valid cases in which a user does not want a blank line between a
+  ;; results block and the subsequent text.
   (beginning-of-line 0)
   (when hash (org-babel-hide-hash)))
 
-- 
2.31.1


                 reply	other threads:[~2021-12-30 15:27 UTC|newest]

Thread overview: [no followups] expand[flat|nested]  mbox.gz  Atom feed

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.orgmode.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=CA+X8ke4K0N5fS8Ukr+4kX0aPOv+63eoU3naARMY8DfYTTez_TA@mail.gmail.com \
    --to=huszaghmatt@gmail.com \
    --cc=emacs-orgmode@gnu.org \
    --subject='Re: [PATCH] Remove additional newline at end of results block' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Code repositories for project(s) associated with this inbox:

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).