Initial commit

1 files changed, 177 insertions, 0 deletions

diff --git a/cl-tut.org b/cl-tut.org
new file mode 100644
index 0000000..96acd3c
--- /dev/null
+++ b/cl-tut.org
@@ -0,0 +1,177 @@
+
+* Learning Common Lisp and Emacs with an Org Mode Notebook Tutorial
+
+There's a lot to learning Common Lisp, even if you already know how to
+program in some other language.  There's the language itself with its
+many odd features and terms: CONS, CAR and CDR; generic functions and
+multiple dispatch methods; anciliary methods; special variables;
+macros; CLOS and multiple inheritance; the condition system;
+S-expressions; interactive development, and so on.
+
+That would be challenging enough. But then... then there's Emacs.  It
+is oft remarked by wistful Lispers nursing their bitterness about the
+eternal decline of Lisp that if only Emacs weren't so foreign to the
+users of today... if only there were a "more modern" IDE... then maybe
+Lisp would rule the world like it seemed destined to do in the late
+80s and early 90s....
+
+[Aside: A joke about this, btw, is that Common Lisp isn't dead: it's
+Undead]
+
+Fair enough. Emacs *is* in fact, yet another thing to learn. But
+hopefully... well hopefully learning Emacs will pay some dividends
+beyond being able to use SLIME for your Common Lisp work.
+
+This document offers up one such dividend: Orgmode with Babel for
+polyglot computational notebooks.
+
+** What is Orgmode?
+
+[[https://orgmode.org/][Orgmode]] is a text format AND a built-in editor mod for Emacs. Its
+principle purpose is to turn Emacs into a fan-f*cking-tastic editor
+for structured hierarchical documents.
+
+[Aside: That is a link in the above paragraph. Visit it by placing
+your cursor on it and typing =C-c C-o=.
+
+
+You are reading an .org file right now. When Emacs opens file ending
+in .org into a buffer, it becomes aware of several headings, which may
+be collapsed nd expanded at will for quick perusal.
+
+
+Try it. Navigate up to [[*What is Orgmode?][this section's heading]].  Now hit TAB a couple
+of times.
+
+The absolute bare minimum things you need to know about using Org.
+
+1. navigate between headers with =C-c C-n= and =C-c C-p= for the
+   *next* and *previous* headers respectively.
+
+2. Make headlines by typing some number of asterisks and then some
+   text
+
+3. The first headline above this one with fewer leading asterisks is
+   called the *parent* of this headline.  E.g. The headline of this
+   section is "What is Orgmode?" and its parent is "Learning Common
+   Lisp and Emacs with an Org Mode Notebook Tutorial".
+
+4. Headlines with the same parent as this one are called sibling
+   headlines.
+
+5. You can move this headline around among its siblings by typing
+   =M-Up= and =M-Down=.  These same commands work for lists too (like
+   this one! Try it: navigate to the first line of this text and move
+   5 into the 4 spot.
+
+6. You can shift an item into a sub-list or sub-headline by using
+   =M-Left= and =M-Right=.  Again try it with this list!
+
+Pretty cool right? [[https://orgmode.org/features.html][That ain't the half of it]].  Let's keep going!
+
+** Computational Notebooks in Org
+
+To write nice, syntax highlighted code, that you can execute from
+Orgmode, you must place that code inside of a block.
+
+Lets generate one by typing either =M-x org-insert-structure-template=,
+or by typing =C-c C-,= and then hitting =s=. 
+
+Did you do it? 
+
+*** A Python Example
+
+You can write code in practically any language, evaluate it, and embed
+evaluated results right into emacs. Those results can be images,
+tables, strings, whatever.
+
+But, like with most things in Emacs, some configuration is in
+order. Don't worry! You do that from org too!
+
+**** Configure our Emacs to  Execute Python and Lisp from Org
+
+The following block sets a particular variable and loads some code
+associated with it. The details are weedy, but you get the idea.
+
+#+begin_src elisp :results none
+
+(org-babel-do-load-languages
+ 'org-babel-load-languages
+ '((emacs-lisp . t)
+   (python . t)
+   (lisp . t)))
+
+ #+end_src
+
+Now place your curson indide that block and type =C-c C-c=.
+
+Voilà! You should now be able to run Lisp and Python code from Org for
+the reaminder of this Emacs session.
+
+If you want to save those changes, place the above code into your Emacs
+init file.
+
+**** And Now ... Some Python
+
+Nothing fancy, just a function:
+
+#+begin_src python 
+
+def oh_neat(x,y):
+    return x+y
+
+# this is a bit of a hack, but if you want to see the output you need
+# to return something from the block itself.
+return oh_neat(1,2) 
+
+#+end_src
+
+Go ahead, evaluate it with =C-c C-c=
+
+Pretty neat eh?  You can do more than simply return numbers or
+strings: if you wanted to use Emacs as a python notebook, you should
+consult [[https://orgmode.org/worg/org-contrib/babel/languages/ob-doc-python.html][the docs]]. 
+
+** Trying it with Lisp
+
+Before you can evaluate code, you must first start a SLIME session
+with =M-x slime=. So do tha now.
+
+Next, observe the structure of this code block:
+
+#+begin_src lisp :results raw
+
+(defun okcool (cool)
+  cool)
+
+(okcool "cool!")
+
+
+#+end_src
+
+After =begin_src= we have =lisp=. This tells org mode what langauge to
+use. Emacs correctly identifies Common Lisp as the only true Lisp, so
+you need not write =common_lisp= or something equally spurious. 🤣
+
+Second, we specify that we want raw results. Essentially, this is just
+the return value of the last expression in the block.
+
+Go ahead and try it out now with =C-c C-c=
+
+Now that you have defined a function, you can call it in other blocks:
+
+#+begin_src lisp :results raw
+
+(okcool "wow")
+
+#+end_src
+
+Behind the scenes, Org is using SLIME in the normal way.
+
+
+** Fin
+
+So that's the basics. If you like this style, you can use org-mode as
+you learn Common Lisp. Some people find it a dandy way to take notes
+while they work through examples and exercises in various texts.
+