From 0d12f927d049749f960a5b4385c1f8029e859a3b Mon Sep 17 00:00:00 2001
From: Matt <matt@excalamus.com>
Date: Sat, 18 Dec 2021 01:46:29 -0500
Subject: [PATCH] Draft introduction and setup

---
 org-contrib/babel/languages/ob-doc-shell.org | 141 ++++++++++++++++---
 1 file changed, 120 insertions(+), 21 deletions(-)

diff --git a/org-contrib/babel/languages/ob-doc-shell.org b/org-contrib/babel/languages/ob-doc-shell.org
index 46ce0a6f..825e17d2 100644
--- a/org-contrib/babel/languages/ob-doc-shell.org
+++ b/org-contrib/babel/languages/ob-doc-shell.org
@@ -2,7 +2,7 @@
 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate hideblocks
 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
 #+TAGS:       Write(w) Update(u) Fix(f) Check(c) noexport(n)
-#+TITLE:      Shell Source Code Blocks in Org Mode
+#+TITLE:      Shell Code Blocks in Babel
 #+AUTHOR:     Matt Trzcinski
 #+EMAIL:      matt[at]excalamus[dot]com
 #+LANGUAGE:   en
@@ -10,6 +10,9 @@
 #+HTML_LINK_HOME:  https://orgmode.org/worg/
 #+EXCLUDE_TAGS: noexport
 
+# TODO remove this
+#+options: toc:nil
+
 #+name: banner
 #+begin_export html
 <div id="subtitle" style="float: center; text-align: center;">
@@ -26,21 +29,21 @@
     <a href="https://packages.qa.debian.org/p/posh.html">posh</a>.
   </p>
   <p>
-    <a href="https://www.gnu.org/software/bash/">
-      <img src="https://tiswww.case.edu/php/chet/img/bash-logo-web.png"/>
-    </a>
-    <a href="https://www.zsh.org/">zsh</a>,
-      <img src="https://zsh.sourceforge.io/Images/wizard.gif"/>
-    </a>
-    <a href="https://fishshell.com/">fish</a>,
-      <img src="https://fishshell.com/assets/img/Terminal_Logo2_CRT_Flat.png"/>
-    </a>
-    <a href="http://www.kornshell.org/">ksh</a>,
-      <img src="http://www.kornshell.org/kornshell.gif"/>
-    </a>
-    <a href="https://www.mirbsd.org/mksh.htm">mksh</a>, and
-      <img src="https://www.mirbsd.org/pics/logo-grey.png"/>
-    </a>
+    <a href="https://www.gnu.org/software/bash/"><img width="180px"
+    src="https://tiswww.case.edu/php/chet/img/bash-logo-web.png"/></a>
+    
+    <a href="https://www.zsh.org/"><img width="150px"
+    src="https://zsh.sourceforge.io/Images/wizard.gif"/></a>
+
+    <a href="https://www.mirbsd.org/mksh.htm"><img width="150px"
+    src="https://www.mirbsd.org/pics/logo-grey.png"/></a>
+    
+    <a href="https://fishshell.com/"><img width="150px"
+    src="https://fishshell.com/assets/img/Terminal_Logo2_CRT_Flat.png"/></a>
+    
+    <a href="http://www.kornshell.org/"><img width="180px"
+    src="http://www.kornshell.org/kornshell.gif"/></a>
+
   </p>
 </div>
 #+end_export
@@ -63,12 +66,84 @@
   - [ ] Describe [[Other]] differences from supported languages
   - [ ] Provide brief [[Examples of Use][Examples of Use]]
 * Introduction
-  - Brief description of language.
-  - Range of typical uses within Org Mode.
+# - Brief description of language.
+A shell is a user interface for interacting with system services.
+File management, process execution, and operating system monitoring
+can all be done with a shell. Many shells are plain text only whereas
+some support graphics or are themselves fully graphical. Similarities
+exist between shells and, though standards exist (such as
+POSIX[fn:1]), there is no guarantee that what works in one shell will
+work in another. Each shell is a separate application.
+
+Shells often provide a programming language as well as access to
+system utilities, such as the GNU Core Utilities[fn:2]. Users can
+stitch utilities together or create their own.
+
+# - Range of typical uses within Org Mode.
+Org Babel lets users run commands[fn:3] in separate shells...
+
+: #+begin_src sh :results output
+:   echo PID: $$
+: #+end_src
+: 
+: #+RESULTS:
+: : PID: 9952
+: 
+: #+begin_src sh :results output 
+:   echo PID: $$
+: #+end_src
+: 
+: #+RESULTS:
+: : PID: 9990
+: 
+...or as part of a shared session.
+
+: #+begin_src sh :results output :session shared
+:   echo PID: $$
+:   export X=1
+: #+end_src
+: 
+: #+RESULTS:
+: : PID: 9742
+: 
+: #+begin_src sh :results output :session shared
+:   echo PID: $$
+:   echo X was set to $X
+: #+end_src
+: 
+: #+RESULTS:
+: : PID: 9742
+: : X was set to 1
+
+Shell blocks can run as standalone scripts or chained processes, be
+tangled, use args, work with stdin, have shebangs, and more.
+    
 * Requirements and Setup
-  - Installation and configuration of language software
-  - Emacs configuration
-  - Org-mode configuration (org-babel-do-load-languages)
+# - Installation and configuration of language software
+Org Babel can run many different shells, including [[https://www.gnu.org/software/bash/][sh]], [[https://www.gnu.org/software/bash/][bash]], [[https://www.zsh.org/][zsh]],
+[[https://fishshell.com/][fish]], [[https://www.grymoire.com/unix/csh.html][csh]], [[https://www.in-ulm.de/~mascheck/various/ash/][ash]], [[http://gondor.apana.org.au/~herbert/dash/][dash]], [[http://www.kornshell.org/][ksh]], [[https://www.mirbsd.org/mksh.htm][mksh]], and [[https://packages.qa.debian.org/p/posh.html][posh]].  The primary requirement is
+that the shell be installed on the system.
+
+# - Emacs configuration
+# - Org-mode configuration (org-babel-do-load-languages)
+Once the shell is installed on the system, the Org Babel shell
+language facility must be set to load[fn:4]:
+
+#+begin_example emacs-lisp
+;; active Babel languages
+(org-babel-do-load-languages
+ 'org-babel-load-languages
+ '((shell . t)))
+#+end_example
+
+*NOTE:* This is all that's needed, regardless of the shell you intend
+to use! The "shell" <lang> loads functionality for /all/ supported
+shells.  The car of =(shell . t)=, namely "shell", is the name of the
+Org Babel module that handles it, =ob-shell.el=.
+
+*NOTE:* The =ob-shell.el= module used to be named =ob-sh.el=. This was
+changed in Org 8.2[fn:5].
+
 * Babel Features for Language Source Code Blocks
 ** Header Arguments
    - Language-specific default values
@@ -84,3 +159,27 @@
   - Hello World!
   - Common uses
   - Links to tutorials and other resources
+
+* Footnotes
+
+[fn:1] https://opensource.com/article/19/7/what-posix-richard-stallman-explains
+
+[fn:2] https://en.wikipedia.org/wiki/List_of_GNU_Core_Utilities_commands
+
+[fn:3] https://www.gnu.org/savannah-checkouts/gnu/bash/manual/bash.html#index-_0024_0024
+
+[fn:4] https://orgmode.org/worg/org-contrib/babel/languages/index.html#configure
+
+[fn:5] https://git.savannah.gnu.org/cgit/emacs/org-mode.git/tree/etc/ORG-NEWS#n3995 
+
+#+begin_example
+,* Version 8.2
+
+,** Incompatible changes
+,*** =ob-sh.el= renamed to =ob-shell=
+This may require two changes in user config.
+
+1. In =org-babel-do-load-languages=, change =(sh . t)= to =(shell . t)=.
+2. Edit =local.mk= files to change the value of =BTEST_OB_LANGUAGES=
+   to remove "sh" and include "shell".
+#+end_example
-- 
2.34.0

