[WIP] Docs: fill out tutorial nature of the document

cover Emacs, Lisp, and org mode gently as we go along

1 files changed, 70 insertions, 12 deletions

diff --git a/wink-murder.org b/wink-murder.org
index 8b84e7f..e5c3230 100644
--- a/wink-murder.org
+++ b/wink-murder.org
@@ -1,19 +1,63 @@
-* Building a Murder Mystery Game Prototype
+* Building a Murder Mystery Sim Prototype With Emacs
 ** Summary
-ideally a small city/village simulator where there are many independent actors
-all doing their routines. one of them gets triggered by something and commits
-a murder. they will continue to murder any time their pattern is triggered until
-the player figures out who they are.
+
+This document serves as a tutorial for Emacs, Lisp, and org-mode's literate
+programming features. It provides a way to distribute the notes, code, and
+execution environment all in one place. Anyone reading this document can also
+edit and execute the code in it. This is the beauty of literate programs, where
+the program is written for humans as prose with embedded code.
+
+Ideally I would like to create a small city/village simulator where there
+are many independent actors all doing their routines. One of the actors gets
+triggered by something and commits a murder. Then the player acts as detective,
+talking to other actors and gaining clues to solve who-done-it.
 
 ** Wink Murder - boiling it down
 
-the game [[https://en.wikipedia.org/wiki/Wink_murder]["Wink Murder"]] is
-a very simplified version of this, and serves as a starting point to work
-out a prototype. for fun, i'm just doing this in emacs-lisp. the following
-source block represents the whole program from a high level:
+The game [[https://en.wikipedia.org/wiki/Wink_murder]["Wink Murder"]] is
+a simplified murder mystery and serves as a starting point to work out
+a prototype. Actors observe one another while the killer tries to wink at
+any innocent they make eye contact with before being accused and caught. This
+will be a pure simulation, where we can learn about creating actor behavior
+representing knowledge.
+
+Does the killer think they're being watched?
+
+Did one of the innocents notice them wink?
+
+How can we encode some of these behaviors into a simulated version of people
+sitting in a circle and playing this game?
+
+** Org mode
+
+If you're reading this in Emacs, you probably see headings with different colors
+depending on their level. These headings can be folded by pressing TAB when the
+cursor is on them. Navigation by heading is also possible, but we won't worry about
+it for now. Notice in the section above, "Wink Murder" looks like a link. Click
+it. Depending on what you have installed, you should land in a browser at the
+Wikipedia page for the game. If you really like Emacs, you can even use ~eww~ as
+the default browser to open links in. Keep an eye out for links in this program.
+They can be links to nearly anything, like [[info:org#Top][this link to the org-mode info manual]].
+
+I will ask you to learn just *two* keyboard shortcuts. Meta-x and Ctrl-c Ctrl-c.
+(written ~M-x~ and ~C-c C-c~ after this). Meta will be your alt key or possibly
+option, it depends on your machine and OS. ~M-x~ is for ~execute-extended-command~
+which lets you run /any/ command avaliable in Emacs. Combined with a good
+completion engine, it offers one way to discover what things are possible.
+~C-c C-c~ does many things depending on context, in this case, specific to
+~org-mode~. Mostly, you will use it to execute blocks of code in this program.
 
 * Program Overview
 
+The following source block represents the whole program from a high level.
+its like a table of contents, where each of the ~<<name>>~ blocks actually
+points to other source code blocks in this document. The header argument
+~:noweb yes~ tells ~org-mode~ to unfold the references into code, so when
+it sees ~<<dependencies>>~, it will insert the code from the block with
+that name. The header argument ~:tangle yes~ means we can evaluate
+~(org-babel-tangle)~ and it will unfold all of the code references into
+a source file. This is the core of literate programming.
+
 #+name: wink-murder
 #+begin_src emacs-lisp :noweb yes :tangle yes :results silent
   ;;; wink-murder.el --- Emacs Wink-Murder game simulation  -*- lexical-binding:t -*-
@@ -33,16 +77,30 @@ source block represents the whole program from a high level:
   <<game-loop>>
 #+end_src
 
-If you put your cursor on the block above and press C-c C-c, Emacs will
+** Working with source blocks
+
+If you put your cursor on the block above and press ~C-c C-c~, Emacs will
 ask if you want to evaluate the code on your system. This is a good thing,
 since you are executing most of the elisp in this file without looking
 at it! You can set a variable to allow it to execute automatically, but
-its nice to have the safety on.
+its nice to have the safety on. You can turn it off with ~C-c C-c~ on the
+block below:
 
 #+begin_src emacs-lisp
-(setq org-confirm-babel-evaluate nil)
+  (setq org-confirm-babel-evaluate nil)
 #+end_src
 
+** A little bit of Lisp
+
+What does that expression up there do? Its basically the equivalent to
+~variable = value~ in Ruby or other languages. In Lisp, everything is an
+expression, symbols are important, and lists are surrounded with parens.
+When we evaluate Lisp, HERE-IS-WHERE-I-LEFT-OFF
+
+~setq~ actually stands
+for "set quote". ~quote~ is a special form in Lisp that says "don't evaluate
+the next expression, just return it". Var
+
 Now you should be able to press M-x wink-murder-play and it will prompt you for
 a number of players. Enter 4 (lower) will. Then look at the *Messages*
 buffer, you can either find it through the menu bar, ~M-x switch-to-buffer~