From 184ca4acee4c939465a5de8b11b97d9956e8ad74 Mon Sep 17 00:00:00 2001
From: Howard Abrams <howard.abrams@gmail.com>
Date: Sat, 10 Aug 2024 23:33:41 -0700
Subject: [PATCH] Naming and evaluating src blocks

As well as a nifty function for viewing the Info version.
---
 README.org    |  16 ++++++
 lp-in-org.org | 149 ++++++++++++++++++++++++++++++++++++++++++++++----
 2 files changed, 153 insertions(+), 12 deletions(-)

diff --git a/README.org b/README.org
index b5f08cc..784e705 100644
--- a/README.org
+++ b/README.org
@@ -25,3 +25,19 @@ To render and read [[file:lp-in-org.org][the book]] in Info, execute the followi
     (Info-mode)
     (Info-top-node))
 #+end_src
+
+Better yet:
+#+begin_src emacs-lisp :results silent
+  (defun org-view-as-info (file)
+    "View FILE, an org file, as exported to Info page."
+    (ignore-errors
+      (kill-buffer (format "%s.info" (file-name-base file))))
+    (find-file file)
+    (find-file (org-texinfo-export-to-info))
+    (Info-mode)
+    (Info-top-node))
+
+  (defun view-literate-programming-book ()
+    (interactive)
+    (org-view-as-info "~/Documents/literate-programming/lp-in-org.org"))
+#+end_src
diff --git a/lp-in-org.org b/lp-in-org.org
index 53ae79c..3d2accd 100644
--- a/lp-in-org.org
+++ b/lp-in-org.org
@@ -3,14 +3,6 @@
 #+EMAIL:  howard.abrams@gmail.com
 #+DATE:   2016 Oct 06
 #+DESCRIPTION: This file is used as the basis for the Info documentation
-#+OPTIONS: ':t toc:t author:t email:t
-#+LANGUAGE: en
-#+MACRO: version 1.0
-#+MACRO: updated last updated 1 August  2024
-
-#+TEXINFO_FILENAME: lp-in-org.info
-#+TEXINFO_HEADER: @syncodeindex pg cp
-#+TEXINFO_HEADER: @syncodeindex vr cp
 
 # NOTE: To create/view info, execute the following with `C-x C-e':
 # (progn (find-file (org-texinfo-export-to-info)) (Info-mode) (Info-top-node))
@@ -142,7 +134,7 @@ While a classic, not a very good example. Let’s try again with the following c
 
 #+begin_example
 ,#+begin_src emacs-lisp
-  (truncate (* (sin .438) 100))
+  (truncate (* (sin 0.438) 100))
 ,#+end_src
 #+end_example
 
@@ -168,10 +160,10 @@ Note: If you are reading this in an Emacs buffer, you can also place your cursor
 
 At this point, you can begin a line with =<s= and hit ~TAB~ to have a src block expanded, with the cursor left at the end of first line, allowing you to type =emacs-lisp=.
 
-This is Emacs, you probably have your favorite template expansion, like [[https://elpa.gnu.org/packages/doc/tempel/tempel.html][TempEL]] or [[https://www.emacswiki.org/emacs/Yasnippet][Yasnippet]], as any system that can generate your text works fine.The magic isn’t hidden in markers, but shines plainly in the text itself.
+This is Emacs, you probably have your favorite template expansion, like [[https://elpa.gnu.org/packages/doc/tempel/tempel.html][TempEL]] or [[https://www.emacswiki.org/emacs/Yasnippet][Yasnippet]], as any system that can generate your text works fine. Unlike other /notebook applications/, the magic isn’t hidden in markers, but shines plainly in the text itself.
 ** Editing src Blocks
 
-I find editing prose in an Org file quite nice…editing code? Not so much. Many techniques you expect to use, like jumping to code definitions with the [[info:emacs#Looking Up Identifiers][Xref system]] or manipulating s-expressions in a Lisp with =paredit= or =smart-parens=, aren’t available.
+I find editing prose in an Org file quite nice…editing code? Not so much. Many techniques you expect to use aren’t available, like manipulating s-expressions in a Lisp with =paredit= or =smart-parens=, or jumping to code definitions, [[info:emacs#Looking Up Identifiers][Xref system]].
 
 With your cursor anywhere, the header line, anywhere in the body or one the =end_src= line, type ~C-c '~ to narrow to contents of that block with a mode based on the language on the header line.
 
@@ -186,13 +178,130 @@ Let’s add more [[info:org#Languages][languages]] to what is available, by runn
      (python . t)))
 #+end_src
 
-Feel free to substitute the =python=, for your favorite language, or add more. Use =sh= for shell scripts, and =js= for Javascript. See [[https://orgmode.org/worg/org-contrib/babel/languages/index.html][Babel]] for details on languages that can be supported.
+If you aren’t familiar with Lisp, don’t let that magic incantation concern you too much. Just follow the pattern to substitute the =python= for your favorite language. You can add or remove more (use =t= to include it, and =nil= to remove it). Use =sh= for shell scripts, and =js= for Javascript. See [[https://orgmode.org/worg/org-contrib/babel/languages/index.html][Babel]] for details on languages that can be supported.
 
 *Note:* If you don’t see you language’s pretty colors for its syntax, run this code (and put it in your init file):
 
 #+begin_src emacs-lisp
   (setq org-src-fontify-natively t)
 #+end_src
+** Naming src Blocks
+According to Org’s documentation on the [[info:org#Structure of Code Blocks][Structure of Code Blocks]], a =src= block looks like:
+
+#+begin_example
+  ,#+NAME: <name>
+  ,#+BEGIN_SRC <language> <switches> <header arguments>
+    <body>
+  ,#+END_SRC
+#+end_example
+
+The =#+NAME= associates name you can reference later in your document. For instance:
+
+#+begin_example
+  ,#+NAME: the-answer
+  ,#+BEGIN_SRC emacs-lisp
+    (truncate (* (1- (expt 2 3)) (sqrt 36)))
+  ,#+END_SRC
+
+  ,#+RESULTS: the-answer
+  : 42
+#+end_example
+
+The named value, =the-answer= isn’t a variable, but the following sections, we’ll show how it can be used as one.
+
+Following the /language/, you can add switches and other header arguments (that we will discuss ad nauseam in the following sections). Sometimes, we have too many arguments to /comfortably/ fit on a line, so we can break those long lines:
+
+#+begin_example
+  ,#+NAME: <name>
+  ,#+HEADER: <more header arguments>
+  ,#+BEGIN_SRC <language> <switches> <header arguments>
+    <body>
+  ,#+END_SRC
+#+end_example
+
+You can have as many =#+HEADER= lines as you want.
+
+** Evaluating src Blocks
+As described above, typing ~C-c C-c~ in a block, evaluates it, displaying the results.
+
+Why doesn’t the following work?
+
+#+begin_example
+  ,#+BEGIN_SRC python
+    print("Hello World")
+  ,#+end_SRC
+
+  ,#+RESULTS:
+  : None
+#+end_example
+
+The reason is that  Python, by default, only returns the results from the /value/ of an expression, and the =print= function returns =None=. To see the /output/ from a block, we need to  add a =:results= header argument:
+
+#+begin_example
+  ,#+BEGIN_SRC python :results output
+    print("Hello World")
+  ,#+END_SRC
+
+  ,#+RESULTS:
+  : Hello World
+#+end_example
+
+Some languages, like =sh= (for your shell) default to =output=, so the following works as expected:
+
+#+begin_example
+  ,#+BEGIN_SRC sh
+    pwd
+  ,#+END_SRC
+
+  ,#+RESULTS:
+  : /home/howard/Documents/literate-programming
+#+end_example
+
+If a language, like Python, can return either a /value/ or its /standard output/, you can set =:results= to =value= or =output= respectively.
+*** Displaying Results as Lists
+Our previous examples returned a single number or string. If our code returned an array or list, we can use the =:results= header argument to state you want the results formatted as a list:
+
+#+begin_example
+  ,#+BEGIN_SRC emacs-lisp :results list
+    (number-sequence 1 5)
+  ,#+END_SRC
+
+  ,#+RESULTS:
+  - 1
+  - 2
+  - 3
+  - 4
+  - 5
+#+end_example
+
+In the [[*Evaluating src Blocks][previous section]], we used =:results= to specify whether we wanted the /value/ of the code, or its /standard output/, but the =:results= header argument can take multiple arguments, for instance, all of the following are reasonable:
+
+  - =:results value=
+  - =:results list=
+  - =:results value list=
+*** Displaying Results as Tables
+The =:results= header argument accepts the =table= parameter, which is helpful for two-dimensional arrays.
+
+#+begin_example
+  ,#+BEGIN_SRC emacs-lisp :results table
+    (defun rando (limit) (random limit))
+
+    (defun lotso-randos ()
+      (seq-map 'rando (number-sequence 1 25)))
+
+    (seq-partition (lotso-randos) 5)
+  ,#+END_SRC
+
+  ,#+RESULTS:
+  |  0 |  0 |  0 | 3 |  1 |
+  |  4 |  3 |  6 | 6 |  3 |
+  |  2 | 10 |  9 | 6 |  4 |
+  |  7 | 13 |  0 | 0 | 10 |
+  | 20 | 20 | 17 | 3 |  4 |
+#+end_example
+
+Shall we talk about state?
+*** Displaying Results as Code
 
 * Working with Python
 * Calling out to the Shell
@@ -248,3 +357,19 @@ And maybe another one for defining unit tests?
     (should (= $0)))
   ,#+END_SRC
 #+end_example
+** Hacking
+Note the function =org-in-block-p= to see if we are in a “src” block.
+
+
+#+OPTIONS: ':t toc:t author:t email:t
+#+LANGUAGE: en_US
+#+MACRO: version 1.0
+#+MACRO: updated last updated 1 August  2024
+
+#+TEXINFO_FILENAME: lp-in-org.info
+#+TEXINFO_HEADER: @syncodeindex pg cp
+#+TEXINFO_HEADER: @syncodeindex vr cp
+
+# Local Variables:
+# jinx-local-words: "src"
+# End: