How to denote an aside in org?

Question

I am trying to go deeper with org mode to the literate coding stuff itself rather than merely for markup.

I am writing a document where I'm solving some coding challenge, and part way through reasoning about it, decide to take an aside to ensure that I know how to pass tables into src blocks and to use sessions. The next section of my document is a sort of "aside" where I am testing just that (though using some of the named tables in the containing header). I then want to return to solving the problem.

So I have

* My problem
  writing
  src block
  writing
  a-named-table
  more writing

  here's my aside, writing
  src block
  writing
  src
  writing
  src

  writing, back to the main thing, I'm not referencing anything in the aside here

What is a good way of denoting that aside so that I can expand/collapse it and control whether I want it exported or not later?

I could use a headline but then returning to the main code would require its own headline which would be weird in the outline as it would split up what is one logical flow of thought into two simply because an aside was nestled between.

I use asides in writing prose a lot so I think it would probably be beneficial for my literate coding efforts to know the "right" way of doing it.

The question is primarily opinion-based, so it risks being closed. "Best way" questions are generally frowned on here. Specific how-to or how-to-understand questions and specific answers are what this site is about. — Drew, Oct 14 '19 at 15:55
Fair enough @Drew I can reword. The issue really is *some* way of properly representing it. A header item seems wrong since it would break up the outline of what would naturally be "one thing" into two. I've also looked at drawers but it seems like I can't place properties on them? — George Mauer, Oct 14 '19 at 16:05

Tobias · Accepted Answer · 2019-10-14T16:45:56.990

You can use the executable org source blocks from the answer to another question.

Write your aside into that org source block. That gives your the possibility to structure your aside and to include almost everything that is possible in org mode into the aside.

With the :exports header argument you can freely export the source code of the org source block (code), the resulting org mode code (results), or nothing at all (none).

Citation of the function enabling the export of org source blocks:

(defun org-babel-execute:org (body params)
  "Return BODY with variables from PARAMS replaced by their values."
  (let* ((vars (cl-loop for par in params
            if (eq (car par) :var)
            collect (cons (symbol-name (cadr par)) (cddr par))))
     (re (regexp-opt (mapcar #'car vars) 'words))
     (pos 0))
    (while (string-match re body pos)
      (setq body (replace-match
          (format "%s" (cdr (assoc-string (match-string 0 body) vars)))
          nil nil
          body)))
    body))

There follows the org code for your document. The :results: drawer is generated by the execution of the org source block.
You can fold the org source block and also the :results: drawer.

** My problem
  writing
  src block
  writing
  a-named-table
  more writing

#+begin_src org :results drawer :exports results
here's my aside, writing
,#+begin_src emacs-lisp
(message "Hello world!")
,#+end_src
writing
,#+begin_src emacs-lisp
(message "Src block 2!")
,#+end_src
writing
,#+begin_src emacs-lisp
(message "Src block 3!")
,#+end_src
#+end_src

#+RESULTS:
:results:
here's my aside, writing
#+begin_src emacs-lisp
(message "Hello world!")
#+end_src
writing
#+begin_src emacs-lisp
(message "Src block 2!")
#+end_src
writing
#+begin_src emacs-lisp
(message "Src block 3!")
#+end_src
:end:

  writing, back to the main thing, I'm not referencing anything in the aside here

Exporting the resulting org source with :exports results header argument:

Exporting the source code from the org source block with :exports code header argument:

Exporting nothing related to the org source block with :exports none header argument:

woah...so ...the aside itslef would be an org src block? wild! — George Mauer, Oct 14 '19 at 16:29
@GeorgeMauer Yes, you can even use the substitution of source block variables inside the org source block. — Tobias, Oct 14 '19 at 16:30

score 0 · Answer 2 · answered Oct 14 '19 at 19:51

This sounds like a job for "inline tasks" (FAQ entry: https://orgmode.org/worg/org-faq.html#list-item-as-todo).

There's another answer here that shows them, including choosing to export or not to export via "OPTIONS": https://emacs.stackexchange.com/a/34504/737 -- I suggest you upvote that one rather than this one if that helps, since I'm not reproducing the answer here.

How to denote an aside in org?

2 Answers2