#+PROPERTY: header-args :tangle "./.org-mode-fundamentals.emacs.el" :results output silent
#+OPTIONS: toc:3

Never compile this.

#+NAME: org_gcr_2017-07-21_mara_495928F4-D984-4DE8-9513-C94FEFD9CDB0
#+BEGIN_SRC emacs-lisp :comments no
;; -*- no-byte-compile: t; -*-
#+END_SRC

* Org-Mode Fundamentals
   :PROPERTIES:
   :ID:       orgmode:gcr:vela:7E71A009-4DD3-4296-9851-293BC71D2DFF
   :END:

Configure Org-Mode core functionality to compile this system.

Sysop is likely to use this periodically.

Start EMACS with this command:

#+BEGIN_EXAMPLE
emacs --debug-init --no-init-file --no-splash --background-color white --foreground-color black --vertical-scroll-bars --eval '(switch-to-buffer "*Messages*")' --name FND-TEST --title FND-TEST --load ~/src/help/.org-mode-fundamentals.emacs.el &
#+END_EXAMPLE

#+NAME: org_gcr_2017-05-12_mara_71A4A257-9A13-457A-B504-888D8131A206
#+BEGIN_SRC emacs-lisp
(load-file "~/src/help/.org-mode-ecm.emacs.el")
#+END_SRC

** Literate Programming
  :PROPERTIES:
  :ID:       orgmode:gcr:vela:8510C876-F644-4804-9F87-54A0B44DBA6A
  :END:

#+MACRO: lp-configure-each-sb Configuration likely per Source-Block or System.

This system enables you to perform 3 Literate Document activities
- Tangling
- Evaluating
- Weaving

Combined they provide a rich Literate Programming environment.

These activities are not performed interactively by the user. They are automatic
operations that occur as a result of the configuration by the document itself.

The following is the guide for the default configuration of this system and how
it behaves.

Key:

- Columns
  - S :: Source document modified?
  - T :: Destination tangled-document modified?
  - W :: Destination weaved-document modified?
  - C :: Source-Block Evaluation occurred?
  - O :: Org-Macro Expansion occurred?

| Activity   | S | T | W | C  | O |
|------------+---+---+---+----+---|
| Tangling   | F | T | F | F  | F |
| Evaluating | T | F | F | T  | F |
| Weaving    | F | F | T | F! | T |

They are separate and distinct operations.

"Programming" is logically an activity that is the combination of these 3
activites. It is interactively performed by Sysop. It is not a distinct
or isolated operation. Results of one activity exist here and serve as inputs to
another activity.

- Note about ~F!~: Weaving Source-Block Evaluation occurred?^{*}
  - Source block evaluation on export is disabled using header arguments:
    those source blocks will never be evaluated on weaving
  - However the /ability/ for them evaluate on weaving /is/ enabled so that weaved
    source blocks can be replaced by their result value. This gives a kind of
    template system. More details [[eval][here]]

*** Helper Functions
   :PROPERTIES:
   :ID:       orgmode:gcr:vela:B14776FD-6835-4D1D-BCD3-50D56555423C
   :END:

Help configure Org-Mode.

#+NAME: org_gcr_2017-05-12_mara_21BEDC86-D1A3-43FC-85AC-8FF54D161E2F
#+BEGIN_SRC emacs-lisp
(defun help/set-org-babel-default-header-args (property value)
  "Easily set system header arguments in org mode.

PROPERTY is the system-wide value that you would like to modify.

VALUE is the new value you wish to store.

Attribution: URL `http://orgmode.org/manual/System_002dwide-header-arguments.html#System_002dwide-header-arguments'"
  (setq org-babel-default-header-args
        (cons (cons property value)
              (assq-delete-all property org-babel-default-header-args))))

(defun help/set-org-babel-default-inline-header-args (property value)
  "See `help/set-org-babel-default-header-args'; same but for inline header args."
  (setq org-babel-default-inline-header-args
        (cons (cons property value)
              (assq-delete-all property org-babel-default-inline-header-args))))

(defun help/set-org-babel-default-header-args:R (property value)
  "See `help/set-org-babel-default-header-args'; same but for R.

This is a copy and paste. Additional languages would warrant a refactor."
  (setq org-babel-default-header-args:R
        (cons (cons property value)
              (assq-delete-all property org-babel-default-header-args:R))))

(defun help/set-org-babel-default-header-args:ditaa (property value)
  "See `help/set-org-babel-default-header-args'; same but for ditaa.

This is a copy and paste. Additional languages would warrant a refactor."
  (setq org-babel-default-header-args:ditaa
        (cons (cons property value)
              (assq-delete-all property org-babel-default-header-args:ditaa))))

(defun help/set-org-babel-default-header-args:dot (property value)
  "See `help/set-org-babel-default-header-args'; same but for dot.

This is a copy and paste. Additional languages would warrant a refactor."
  (setq org-babel-default-header-args:dot
        (cons (cons property value)
              (assq-delete-all property org-babel-default-header-args:dot))))

(defun help/set-org-babel-default-header-args:plantuml (property value)
  "See `help/set-org-babel-default-header-args'; same but for plantuml.

This is a copy and paste. Additional languages would warrant a refactor."
  (setq org-babel-default-header-args:plantuml
        (cons (cons property value)
              (assq-delete-all property org-babel-default-header-args:plantuml))))

(defun help/org-toggle-macro-markers ()
  (interactive)
  (let ((old org-hide-macro-markers)
        (new (not org-hide-macro-markers)))
    (setq org-hide-macro-markers new)
    (message "Just changed org-hide-macro-markers from %s to %s" old new)
    (font-lock-mode)
    (font-lock-mode)))

(defun help/org-prp-hdln ()
  "Visit every Headline. If it doesn't have an ID property then add one and
  assign it a UUID. Attribution: URL
  `http://article.gmane.org/gmane.emacs.orgmode/99738'. It is OK to leave the
  colon separator in here because these are never used as Source-Blocks and
  the rest of the code expects the colon separator."
  (interactive)
  (save-excursion
    (goto-char (point-min))
    (dolist (p (nreverse
                (org-element-map (org-element-parse-buffer 'headline) 'headline
                  (lambda (headline) (org-element-property :begin headline)))))
      (goto-char p)
      (org-id-get-create))
    (save-buffer)))

(defun help/org-id-new ()
  "Re-purposing `org-id' hit a snag when colons were forbidden in Source-Block
  names. Adding support for a user-defined Org-Id separator would have fixed
  this but with no benefit to Org-Id. So this function removes the colon
  instead.
 "
  (interactive)
  (let* ((gend (org-id-new))
         (newid (replace-regexp-in-string ":" "_" gend)))
    newid))

(defun help/org-prp-src-blk ()
  "If it doesn't have a NAME property then add one and
   assign it a UUID. Attribution: URL `http://article.gmane.org/gmane.emacs.orgmode/99740'"
  (interactive)
  (help/org-2every-src-block
   #'(lambda (element)
       (if (not (org-element-property :name element))
           (let ((i (org-get-indentation)))
             (beginning-of-line)
             (save-excursion (insert "#+NAME: " (help/org-id-new) "\n"))
             (indent-to i)
             (forward-line 2))))))

(defconst help/org-special-pre "^\s*#[+]")

(defun help/org-2every-src-block (fn)
  "Visit every Source-Block and evaluate `FN'."
  (interactive)
  (save-excursion
    (goto-char (point-min))
    (let ((case-fold-search t))
      (while (re-search-forward (concat help/org-special-pre "BEGIN_SRC") nil t)
        (let ((element (org-element-at-point)))
          (when (eq (org-element-type element) 'src-block)
            (funcall fn element)))))
    (save-buffer)))

(defun help/org-babel-demarcate-block ()
  "Add a NAME property then assign it a UUID."
  (interactive)
  (org-babel-demarcate-block)
  (insert "#+name: " (help/org-id-new))
  (beginning-of-line)
  (insert "\n"))
#+END_SRC

*** Identity
:PROPERTIES:
:ID:       orgmode:gcr:vela:25F4226F-2EB2-48EC-A4D5-56DD5CCC753E
:END:

A Headline's primary key is =ID=. Use =org-id= to manage it.

#+NAME: org_gcr_2017-05-12_mara_922805E3-E016-4026-BAF6-C3BA5DFC6B5A
#+BEGIN_SRC emacs-lisp
(require 'org-id)
#+END_SRC

In Links: Never use =ID= or =CUSTOM_ID=; always use the file name and text to make
it accessible outside of Emacs.

#+NAME: org_gcr_2017-05-12_mara_6F578996-A506-4193-8566-C3FAC6102228
#+BEGIN_SRC emacs-lisp
(setq org-id-link-to-org-use-id 'nil)
#+END_SRC

Make sure that =ID= is always unique, portable, and easy to maintain by
- Using an acceptable prefix
  - Memorable
    - So you can remember where you created it and when
    - So you can share it and let the recipient know (in theory useful)
    - So you can enable a non Emacs/Org-Mode user to work with the tangled
      code referencing it's origin
  - Valid
    - Must be both LaTeX label and XHTML identifier compliant
      - ~org-lint~ checks for this
- Include the current login
- Include the current domain
- Use a UUID

#+NAME: org_gcr_2017-05-12_mara_8F2F5DAE-40B9-490D-8523-BABCAA913A71
#+BEGIN_SRC emacs-lisp
(setq org-id-prefix (concat "org_" (user-real-login-name) "_" (help/get-timestamp-no-colons) "_" (system-name)))
(setq org-id-method 'uuid)
#+END_SRC

*** Tangling
   :PROPERTIES:
   :ID:       orgmode:gcr:vela:267EEDED-1367-405F-807C-B3C489045704
   :END:
=ID= and =NAME= are essential for successful =LP= using ~org-babel-tangle-jump-to-org~.

#+NAME: org_gcr_2017-05-12_mara_C4C2CC56-88D6-440F-A277-75B174B7F8E8
#+BEGIN_SRC emacs-lisp
(add-hook 'org-babel-pre-tangle-hook #'help/org-prp-hdln)
(add-hook 'org-babel-pre-tangle-hook #'help/org-prp-src-blk)
#+END_SRC

There is a way to disable property inheritance that speeds up tangling a lot.
This is only for user-defined properties; *not* Org-Mode properties.

The problem is that you lose property inheritance which is unacceptable. Never,
never allow that. Its inconsistent with how Org-Mode works.

#+NAME: org_gcr_2017-05-12_mara_7AFF21D6-39A6-4580-8AD1-3BF24A83091A
#+BEGIN_SRC emacs-lisp
(setq org-babel-use-quick-and-dirty-noweb-expansion nil)
#+END_SRC

Assume that tangled document always live within the same directory structure
as their origin document.

#+NAME: org_gcr_2017-05-12_mara_BFB80EA4-F37F-484C-9A7E-7B97166A2F49
#+BEGIN_SRC emacs-lisp
(setq org-babel-tangle-use-relative-file-links t)
#+END_SRC

- Post tangle actions
  - Indentation
    - At first glance this is surprising! The author should be responsible for
      the indentation, right? Yes, that is right. But there is one exception:
      using ~:noweb-ref~ source block concatenation. [[http://orgmode.org/manual/noweb_002dref.html][It]] is powerful and elegant.
      But the source blocks are indented on their own line. It forces any
      reader format it to make any sense of it. That is a poor start to using
      the tangled files. So tangled files get indented.

#+NAME: org_gcr_2017-05-12_mara_1946BB7D-D2A7-40F3-BF7D-1C22B887D1F6
#+BEGIN_SRC emacs-lisp
(defun help/org-babel-post-tangle-hook-fn ()
  (interactive)
  (indent-region (point-min) (point-max) nil)
  (save-buffer))
(add-hook 'org-babel-post-tangle-hook #'help/org-babel-post-tangle-hook-fn)
#+END_SRC

**** comments
    :PROPERTIES:
    :ID:       orgmode:gcr:vela:49787FC5-CAA7-466B-B742-0F38973E070B
    :END:

#+BEGIN_QUOTE
Toggle insertion of comments in tangled code files
#+END_QUOTE

Provide as much information as possible in the tangled artifact about the
origin artifact.

#+NAME: org_gcr_2017-05-12_mara_5516E87C-58CA-451B-84B3-BA7B9D2A284E
#+BEGIN_SRC emacs-lisp
(help/set-org-babel-default-header-args :comments "noweb")
#+END_SRC

**** mkdirp
    :PROPERTIES:
    :ID:       orgmode:gcr:vela:B0F9A321-3B69-46BB-B512-0AF3C663A4C0
    :END:

#+BEGIN_QUOTE
Toggle creation of parent directories of target files during tangling
#+END_QUOTE

#+NAME: org_gcr_2017-05-12_mara_51AE0BB2-9E85-482C-AAC6-8860D2141999
#+BEGIN_SRC emacs-lisp
(help/set-org-babel-default-header-args :mkdirp "yes")
#+END_SRC

**** no-expand
    :PROPERTIES:
    :ID:       orgmode:gcr:vela:90170E6A-AA1A-44EA-9BF8-1A6AA38FD224
    :END:

#+BEGIN_QUOTE
Turn off variable assignment and noweb expansion during tangling
#+END_QUOTE

{{{lp-configure-each-sb}}}

**** noweb
    :PROPERTIES:
    :ID:       orgmode:gcr:vela:E12B48AB-68E8-4515-89E3-30A16FB6FD22
    :END:

#+BEGIN_QUOTE
Toggle expansion of noweb references
#+END_QUOTE

Expand noweb references in source-blocks before:

| Activity   | Expand |
|------------+--------|
| Tangling   | T      |
| Evaluating | T      |
| Weaving    | F      |

This embraces the notion that you are telling the right thing to the
computer and the right thing to the human. By the time you get to exporting, you
ought to refer to the generated document.

#+NAME: org_gcr_2017-05-12_mara_F9D0273A-A0E4-4265-B133-C665ADE1F031
#+BEGIN_SRC emacs-lisp
(help/set-org-babel-default-header-args :noweb "no-export")
#+END_SRC

**** noweb-ref
    :PROPERTIES:
    :ID:       orgmode:gcr:vela:2836D0AA-5DBA-48AC-A338-B47002DE8D7F
    :END:

#+BEGIN_QUOTE
Specify block's noweb reference resolution target
#+END_QUOTE

{{{lp-configure-each-sb}}}

**** noweb-sep
    :PROPERTIES:
    :ID:       orgmode:gcr:vela:B1A57D15-6BBF-4E78-A0D9-0B02C283C6B0
    :END:

#+BEGIN_QUOTE
String used to separate noweb references
#+END_QUOTE

{{{lp-configure-each-sb}}}

**** padline
    :PROPERTIES:
    :ID:       orgmode:gcr:vela:DDE727A6-DDF7-4B61-9063-549614B135F0
    :END:

#+BEGIN_QUOTE
Control insertion of padding lines in tangled code files
#+END_QUOTE

- ~org-babel-tangle-jump-to-org~ requires padded lines. This configuration could
  arguably appear in the "Programming" heading because it impacts operation. It
  lives here because it *must* occur as part of the Tangling activity so that it
  can be used in the Programming activity.
- Often I go back and for on this one. Sometimes it is nicer to have less spaces
  in generated code when guests are viewing it. When no one else is reading it
  I love the spaces. Defaulting to what I like.

#+NAME: org_gcr_2017-05-12_mara_D7CD2E35-5BE4-4003-8D78-26D939E0031E
#+BEGIN_SRC emacs-lisp
(help/set-org-babel-default-header-args :padline "yes")
#+END_SRC

**** session
    :PROPERTIES:
    :ID:       orgmode:gcr:vela:8219A42A-E90F-418A-8EF0-EB150CF6D730
    :END:

#+BEGIN_QUOTE
Preserve the state of code evaluation
#+END_QUOTE

{{{lp-configure-each-sb}}}

For some situations, this may be the same for every source block for a
particular language. R is a good example.

**** shebang
    :PROPERTIES:
    :ID:       orgmode:gcr:vela:542185DD-4FD6-459A-B422-DA7B546FB292
    :END:

#+BEGIN_QUOTE
Make tangled files executable
#+END_QUOTE

{{{lp-configure-each-sb}}}

**** tangle
    :PROPERTIES:
    :ID:       orgmode:gcr:vela:EA716FC9-4A90-4F3E-ABD0-31FEA575C969
    :END:

#+BEGIN_QUOTE
Toggle tangling and specify file name
#+END_QUOTE

#+NAME: org_gcr_2017-05-12_mara_B11664F9-C0E7-48C0-8050-0A66B199FEBF
#+BEGIN_SRC emacs-lisp
(help/set-org-babel-default-header-args :tangle "no")
#+END_SRC

**** tangle-mode
    :PROPERTIES:
    :ID:       orgmode:gcr:vela:5F0B7157-2DC8-4AFD-8F26-4B21025A5ECE
    :END:

#+BEGIN_QUOTE
Set permission of tangled files
#+END_QUOTE

{{{lp-configure-each-sb}}}

*** Evaluating
   :PROPERTIES:
   :ID:       orgmode:gcr:vela:ED23FF0B-1F90-435C-9B56-ACA06C1ACAE0
   :END:

Org-Mode may use all of the listed languages.

#+NAME: org_gcr_2017-05-12_mara_54FEB960-2B87-41E3-A4E4-6DE9DED9B1BD
#+BEGIN_SRC emacs-lisp
(org-babel-do-load-languages
 'org-babel-load-languages
 '((emacs-lisp . t)
   (org . t)
   ;;
   (C . t)
   (R . t)
   (python . t)
   (sass . t)
   (scheme . t)
   (sql . t)
   (js . t)
   ;;
   (latex . t)
   ;;
   (makefile . t)
   (shell . t)
   ;;
   (ditaa . t)
   (dot . t)
   (plantuml . t)))
#+END_SRC
**** cache
    :PROPERTIES:
    :ID:       orgmode:gcr:vela:49B8BFE9-643B-450F-A8A1-20CE3079E215
    :END:

#+BEGIN_QUOTE
Avoid re-evaluating unchanged code blocks
#+END_QUOTE

{{{lp-configure-each-sb}}}

Default =no= is correct for nearly every scenario.

**** colnames
    :PROPERTIES:
    :ID:       orgmode:gcr:vela:4D683007-14AE-4A7D-A506-E2301FD32E82
    :END:

#+BEGIN_QUOTE
Handle column names in tables
#+END_QUOTE

{{{lp-configure-each-sb}}}

**** dir
    :PROPERTIES:
    :ID:       orgmode:gcr:vela:CD1494F1-0A2A-44D0-9955-0D0501AF1539
    :END:

#+BEGIN_QUOTE
Specify the default (possibly remote) directory for code block execution
#+END_QUOTE

{{{lp-configure-each-sb}}}

**** epilogue
    :PROPERTIES:
    :ID:       orgmode:gcr:vela:CA7F5086-9D4B-4847-9449-3231CE027804
    :END:

#+BEGIN_QUOTE
Text to append to code block body
#+END_QUOTE

See Prologue.

**** eval
    :PROPERTIES:
    :ID:       orgmode:gcr:vela:0329BACE-2C99-4BB3-A7A5-7C800EF53FAD
    :END:

#+BEGIN_QUOTE
Limit evaluation of specific code blocks
#+END_QUOTE

Never evaluate source-blocks or in-line-source-blocks *on export*.

#+NAME: org_gcr_2017-05-12_mara_FE5C21BF-9766-4277-A413-B3AF5C255C39
#+BEGIN_SRC emacs-lisp
(help/set-org-babel-default-header-args :eval "never-export")
(help/set-org-babel-default-inline-header-args :eval "never-export")
#+END_SRC

~org-export-use-babel~

How does this overlap with the ~:eval~ header arg? Are they the same or
different? What is the point? For a while I thought I understood the
difference and how it worked. Later when I ran into a problem with my exports
I realized that I didn't understand the difference!

I thought that I had configured inline source blocks to

1) Have their results replaced on each export
2) Only include their results, excluding their source code
3) Allow execution of source blocks interactively, never on export

It is all documented here [[Literate Programming]].

Instead of that, when I exported, the results /weren't/ replaced and the source
code /was/ included: exactly the opposite of what I had wanted to happen. Ouch!

Source blocks include a header arg ~:eval~ that controls evaluation of source
blocks. I'd configured them all (both normal source blocks and inline source
blocks) with the setting "never-export". Never-export makes it so that you can
evaluate source blocks when you are editing the document but they can never be
evaluated during export. That is why #3 worked correctly. But I will still
stuck with #1-#2.

Long story short after reviewing what I was thought every setting regarding
evaluating and exportation I ended up on ~org-export-use-babel~. It seemed silly
to read it's documentation again because I'd read it so many times that I
though I knew it inside and out: it controls whether or not code blocks /can/ be
evaluated on export. I'd set it to true though, to be totally sure that the
system worked as I had expected. Now *two* places disabled evaluation on export:
header args and this variable. It was here though that my understanding had a
major mistake!

~org-export-use-babel—~ answers two questions (controls two features) with one
answer:

1) Is code evaluated on export?
2) Are header args obeyed?

The key is the second part: the header args must be obeyed to make ~replace~
work. My problem was that I never noticed that this variable controls both
execution and header args use. The latter, somehow I totally missed that. So
no matter how I configured the header-args, those results /could never/ be
replaced because the header-args are *totally ignored*. Wow, I was so happy to
discover this.

In the end the configuration was super simple: set ~org-export-use-babel~ to
true, make sure the desired source blocks were set to ~:never-export~, and the
inline source blocks were setup to replace.

#+NAME: org_gcr_2017-05-12_mara_DB816700-04B3-45D0-9847-490BBFE9DBA0
#+BEGIN_SRC emacs-lisp
(setq org-export-use-babel t)
#+END_SRC

**** file
    :PROPERTIES:
    :ID:       orgmode:gcr:vela:80824708-62AF-4337-A517-828DA22D1FCA
    :END:

#+BEGIN_QUOTE
Specify a path for file output
#+END_QUOTE

{{{lp-configure-each-sb}}}

**** file-desc
    :PROPERTIES:
    :ID:       orgmode:gcr:vela:6F9A2745-7118-469E-9FDB-4B327C02E5FA
    :END:

#+BEGIN_QUOTE
Specify a description for file results
#+END_QUOTE

{{{lp-configure-each-sb}}}

**** file-ext
    :PROPERTIES:
    :ID:       orgmode:gcr:vela:0716A48E-9227-44FD-B1FA-185DF6545E91
    :END:

#+BEGIN_QUOTE
Specify an extension for file output
#+END_QUOTE

{{{lp-configure-each-sb}}}

**** hlines
    :PROPERTIES:
    :ID:       orgmode:gcr:vela:721F4E5E-A343-4D7C-A3A3-12A544B3A273
    :END:

#+BEGIN_QUOTE
Handle horizontal lines in tables
#+END_QUOTE

{{{lp-configure-each-sb}}}

**** output-dir
    :PROPERTIES:
    :ID:       orgmode:gcr:vela:D0DDFE88-1B41-4A67-A5F4-88B1B35A7513
    :END:

#+BEGIN_QUOTE
Specify a directory to write file output to
#+END_QUOTE

{{{lp-configure-each-sb}}}

One example is a System where *all* intermediate results are stored to individual
files.

**** post
    :PROPERTIES:
    :ID:       orgmode:gcr:vela:1A4DEC98-C735-4D88-8261-6AD13C495EF2
    :END:

#+BEGIN_QUOTE
Post processing of code block results
#+END_QUOTE

{{{lp-configure-each-sb}}}

**** prologue
    :PROPERTIES:
    :ID:       orgmode:gcr:vela:3D1780E0-2E6D-428C-916D-BFB10E79C76F
    :END:

#+BEGIN_QUOTE
Text to prepend to code block body
#+END_QUOTE

{{{lp-configure-each-sb}}}

For some situations, this may be the same for every source block for a
particular language. The user manual described ~gnuplot~, which often shows up on
the list and the solution is to ~reset~ the session.

Another example, say that you've got a bunch of R Source-Blocks and you want to
be able to rearrange them as you please. You want to be sure that there are no
dependencies between them on bindings created in the workspace. Set ~prologue~
to ~rm(list = ls())~.

Epilgue works hand-in-hand with this.

**** results
    :PROPERTIES:
    :ID:       orgmode:gcr:vela:2755571E-113B-436E-9EEC-26618A55A27E
    :END:

#+BEGIN_QUOTE
Specify the type of results and how they will be collected and handled
#+END_QUOTE

Ways to configure =:results=: src_emacs-lisp{(apply '* (-keep 'cdr '((Collection . 2) (Type . 4) (Format . 7) (Handling . 4))))} {{{results(=224=)}}}.

This system stores the results of evaluation in the source document. It believes
that the results are critical to the research.

Keep the document as close to being executable as possible; make it very visible
when it is not.

- Collection
  - =value=: Functions have a single result. So do Source-Blocks.
- Type
  - =scalar=
    - Functions always return a single result
    - Evidence demonstrates that I use this or =output= most of the time and I
      want to configure this to work right for =Literate Programming= by default
      because it feels better.
  - =WAS=
    - Because in theory returning a collection was flexible (see below). In
      practice I never ever used this.
    - =table=:
      - Tables are the best type because
        - Dimensions make them human-readable in text.
        - Work with Babel LP.
        - Appear as lists to programming languages.
        - Weaves well.
        - Inline Source-Blocks disallow tables so use scalars instead.
- Format
  - =drawer=: Enable results replacement
- Handling
  - =replace=: Replace them each time you evaluate the block.

#+NAME: org_gcr_2017-05-12_mara_2F6FE420-85A2-4A99-AAB7-20473F02B878
#+BEGIN_SRC emacs-lisp
(defconst help/org-sb-results-cfg "value scalar drawer replace")
(help/set-org-babel-default-header-args :results help/org-sb-results-cfg)
#+END_SRC

Their format will show that they are results. Inline source blocks
automatically get formatted as verbatim. For some reason, this only needs to
be configured as =replace= to work unlike normal source blocks. Copying the
configuration from normal source blocks here breaks the replacement
functionality.

#+NAME: org_gcr_2017-05-12_mara_3E59D8A5-2B8A-44D6-A863-7051E8E62421
#+BEGIN_SRC emacs-lisp
(defconst help/org-isb-results-cfg "replace")
(help/set-org-babel-default-inline-header-args :results help/org-isb-results-cfg)
#+END_SRC

**** rownames
    :PROPERTIES:
    :ID:       orgmode:gcr:vela:B184A507-1B03-4096-A4D8-E50A1DA047DB
    :END:

#+BEGIN_QUOTE
Handle row names in tables
#+END_QUOTE

{{{lp-configure-each-sb}}}

**** sep
    :PROPERTIES:
    :ID:       orgmode:gcr:vela:F1336AAA-68EF-4E87-B253-458103B6FF2F
    :END:

#+BEGIN_QUOTE
Delimiter for writing tabular results outside Org
#+END_QUOTE

{{{lp-configure-each-sb}}}

**** var
    :PROPERTIES:
    :ID:       orgmode:gcr:vela:3B4D638C-82EE-47F3-835C-52B2F03620A0
    :END:

#+BEGIN_QUOTE
Pass arguments to code blocks
#+END_QUOTE

- *The* most revealing of the power of Org-Mode's LP offering
- Values-by-reference
  - Table
  - List
  - Source-Block without and with parameters
  - Literal-Block
- Idexable variable values
- Emacs Lisp evaluation of variables

*** Weaving
   :PROPERTIES:
   :ID:       orgmode:gcr:vela:F71DD8BA-B853-4903-A348-400E13C0E6F8
   :END:

Help the reader make sense of the document by displaying it's internal
properties.

#+NAME: org_gcr_2017-05-12_mara_FDA3AE76-9095-49A6-8D3B-F522060FFE0E
#+BEGIN_SRC emacs-lisp
(setq org-export-with-properties t)
#+END_SRC

- Stop your flow to monitor the export for errors
  - <2016-01-19 Tue> Expect it to start weaves for all weavers asynchronously.
    Does not do so; main thread is blocked until weaves complete.

#+NAME: org_gcr_2017-05-12_mara_75498F0F-C121-4954-9E27-B6859173C1E1
#+BEGIN_SRC emacs-lisp
(setq org-export-in-background nil)
#+END_SRC

Make sure that exported files are Unicode UTF-8.

#+NAME: org_gcr_2017-05-12_mara_400FE840-685A-4130-B697-8835F8FDB1FF
#+BEGIN_SRC emacs-lisp
(setq org-export-coding-system 'utf-8)
#+END_SRC

Line breaks are for humans typing them, not for publishing.

When publishing to ASCII, set this property in the file.

#+NAME: org_gcr_2017-05-12_mara_DE83AAE3-B4D6-4AB8-83BF-EE3252F9F6D2
#+BEGIN_SRC emacs-lisp
(setq org-export-preserve-breaks nil)
#+END_SRC

When exporting anything, do not insert the exported content into the kill ring.

#+NAME: org_gcr_2017-05-12_mara_564FC52E-A339-4209-9B6E-86E890D8835C
#+BEGIN_SRC emacs-lisp
(setq org-export-copy-to-kill-ring nil)
#+END_SRC

By default I never want a table of contents generated. It is so easy to enable
it with a property, it will be fine to turn it off.

#+NAME: org_gcr_2017-05-12_mara_BF7F8052-2578-4BA2-9740-DA437B55447B
#+BEGIN_SRC emacs-lisp
(setq org-export-with-toc nil)
#+END_SRC

On export, maintain the literal spacing as found in the source block. Obviously
this is important for make-files. It is really important everywhere because
anything else would violate the law of least surprise.

#+NAME: org_gcr_2017-05-12_mara_5E57CCF7-6D5D-42B4-BD49-26D55EC0891C
#+BEGIN_SRC emacs-lisp
(setq org-src-preserve-indentation t)
#+END_SRC

Maximize flexibility for weaving operations during export.

#+NAME: org_gcr_2017-05-12_mara_BC45B41D-BED3-4448-BFE6-9EE43DAD37E2
#+BEGIN_SRC emacs-lisp
(setq org-export-allow-bind-keywords t)
#+END_SRC

Disable element caching because it might break weaves via [[https://lists.gnu.org/archive/html/emacs-orgmode/2015-09/msg00646.html][this thread]].

#+NAME: org_gcr_2017-05-12_mara_DA69CB4F-597A-4057-A532-2B9EC5E4FCF9
#+BEGIN_SRC emacs-lisp
(setq org-element-use-cache nil)
#+END_SRC

**** exports
    :PROPERTIES:
    :ID:       orgmode:gcr:vela:57B3786B-017F-4F6E-89F9-05642304F3B6
    :END:

#+BEGIN_QUOTE
Export code and/or results
#+END_QUOTE

Always share source blocks and their results. Whether or not to generate a
result for a particular source block is configured per-block. If you don't want
to share a result for a source block then disable storage of results on that
block.

#+NAME: org_gcr_2017-05-12_mara_C933F9D3-EC64-4D09-980D-FB8C7E39CB92
#+BEGIN_SRC emacs-lisp
(help/set-org-babel-default-header-args :exports "both")
#+END_SRC

Use inline Source-Blocks to provide values read as part of the document. Don't
show their source code. Allows inline Source-Blocks to function as /rich/ macros
when combined with ~org-sbe~.

#+NAME: org_gcr_2017-05-12_mara_8D15DF2A-D8EE-4797-AD1C-CB81CFE1404B
#+BEGIN_SRC emacs-lisp
(help/set-org-babel-default-inline-header-args :exports "results")
#+END_SRC

**** wrap
    :PROPERTIES:
    :ID:       orgmode:gcr:vela:94D6B3BE-5DA1-499A-B5C7-A6B71710A1EA
    :END:

#+BEGIN_QUOTE
Mark source block evaluation results
#+END_QUOTE

Inline-Source-Blocks are recognizable by their =verbatim= font. They do not
interrupt the flow. Source-Blocks are their own entities. They stand out. Their
results need to be visibly noticeably different for the reader by making them
=EXAMPLE= special blocks.

#+NAME: org_gcr_2017-05-12_mara_9C45DF8B-120E-47C8-9CA8-04EE6EEB162A
#+BEGIN_SRC emacs-lisp
(help/set-org-babel-default-header-args :wrap "EXAMPLE")
#+END_SRC

Diagramming languages require =RESULTS= output for exporting.

#+NAME: org_gcr_2017-05-12_mara_28D5D5A9-5CC8-4B6C-887F-A02F9D416B0D
#+BEGIN_SRC emacs-lisp
(help/set-org-babel-default-header-args:ditaa :wrap "RESULTS")
(help/set-org-babel-default-header-args:dot :wrap "RESULTS")
(help/set-org-babel-default-header-args:plantuml :wrap "RESULTS")
#+END_SRC

#+RESULTS: orgmode:gcr:vela:0F18A334-A192-4DA5-A897-9D7F3E15C64B
#+BEGIN_EXAMPLE
((:wrap . RESULTS) (:results . file) (:exports . results))
#+END_EXAMPLE