#+OPTIONS:    H:3 num:nil toc:2 \n:nil ::t |:t ^:{} -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc broken-links:nil
#+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 Code Blocks in Babel
#+AUTHOR:     Matt Trzcinski
#+EMAIL:      matt[at]excalamus[dot]com
#+LANGUAGE:   en
#+HTML_LINK_UP:    index.html
#+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;">
  <p>
    Babel shell support, including: <a href="https://www.gnu.org/software/bash/">sh</a>,
    <a href="https://www.gnu.org/software/bash/">bash</a>,
    <a href="https://www.zsh.org/">zsh</a>,
    <a href="https://fishshell.com/">fish</a>,
    <a href="https://www.grymoire.com/unix/csh.html">csh</a>,
    <a href="https://www.in-ulm.de/~mascheck/various/ash/">ash</a>,
    <a href="http://gondor.apana.org.au/~herbert/dash/">dash</a>,
    <a href="http://www.kornshell.org/">ksh</a>,
    <a href="https://www.mirbsd.org/mksh.htm">mksh</a>, and
    <a href="https://packages.qa.debian.org/p/posh.html">posh</a>.
  </p>
  <p>
    <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

* Template Checklist [4/12]                                        :noexport:
  - [X] Revise #+TITLE:
  - [X] Indicate #+AUTHOR:
  - [X] Add #+EMAIL:
  - [X] Revise banner source block [3/3]
    - [X] Add link to a useful language web site
    - [X] Replace "Language" with language name
    - [X] Find a suitable graphic and use it to link to the language
      web site
  - [ ] Write an [[Introduction]]
  - [ ] Describe [[Requirements and Setup][Requirements and Setup]]
  - [ ] Replace "Language" with language name in [[Org Mode Features for Language Source Code Blocks][Babel Features for Language Source Code Blocks]]
  - [ ] Describe [[Header Arguments][Header Arguments]]
  - [ ] Describe support for [[Sessions]]
  - [ ] Describe [[Result Types][Result Types]]
  - [ ] Describe [[Other]] differences from supported languages
  - [ ] Provide brief [[Examples of Use][Examples of Use]]
* Introduction
# - 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
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
   - Language-specific header arguments
** Sessions
   - Support or not
   - Typical use for sessions
** Result Types
   - Which result types are supported?
** Other
   - Differences from other supported languages
* Examples of Use
  - 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