actual README.md, mostly for GitHub; shuffle file layout a bit

README.md

@@ -1 +0,0 @@
-index.md

README.md

@@ -0,0 +1,78 @@
+userland:  a book about the command line for humans
+===================================================
+
+This is the source for some text which can be found here:
+
+[http://p1k3.com/userland-book/](//p1k3.com/userland-book)
+
+...which is probably the best place to read it.
+
+what
+----
+
+From the introduction:
+
+> Late last year, [a side trip](//p1k3.com/2013/8/4) into text utilities got me
+> thinking about how much my writing habits depend on the Linux command line.
+> This struck me as a good hook for talking about the tools I use every day
+> with an audience of mixed technical background.
+>
+> So now I'm writing a (short, haphazard) book.  This isn't a book about system
+> administration, or writing big software systems, or becoming a wizard.  I am
+> not a wizard, and I don't subscribe to the idea that wizardry is a requirement
+> for using these tools.  In fact I barely know what I'm doing most of the time,
+> but I still get some stuff done.
+>
+> My hope herein is to convey something useful to people who use computers every
+> day, but for whom the command line environment seems mystifying, obscure, or
+> generally uninviting.  I intend to gloss over many complexities in favor of
+> demonstrating a rough-and-ready toolset.
+>
+
+[p1k3.com/userland-book.git](//p1k3.com/userland-book.git) is the canonical git
+repo, but I'm pushing everything to a [GitHub
+mirror](https://github.com/brennen/userland-book), and welcome feedback there.
+
+how
+---
+
+This is mostly just some Markdown files and a handful of scripts.  Chapters are
+listed in a file called `chapters`; each chapter is a directory containing an
+`index.md` and any supplemental files.  These are pushed through `render.pl`
+and concatenated with `header.html` & `footer.html`.  For convenience, this is
+handled by a basic `Makefile`:
+
+    $ make
+    cat chapters | xargs ./render.pl | cat header.html - footer.html > index.html
+
+`render.pl` wraps up a library called `Text::Markdown::Discount`, which in turn
+wraps up the Discount Markdown parser.  Aside from this, it also generates a
+table of contents and expands code of the form
+
+    <!-- exec -->
+
+        $ [some command]
+
+    <!-- end -->
+
+to include the output of the command executed in the directory containing the
+rendered file, which is how most of the example commands in the text are
+rendered.  In keeping with long tradition, this is done with cheeseball regex
+substitution.  **Be aware that, by running make, you are implicitly trusting
+most of the commands found in the text to run on your system.**  This is no
+weirder than the level of trust extended to most any build process, but I don't
+want it to catch anyone by surprise.
+
+There's also a `links.md`, which should contain all links to external
+resources.
+
+To build the whole thing without errors, you'd need to be on a system with a
+couple of external repos, Bash and the GNU coreutils, and miscellaneous
+utilities (notably `cowsay`, `dict`, `figlet`, `aspell`, `curl`, `lynx`, and
+`w3m`).  A recent Debian or some derivative would probably work best.  One of
+these days I'll wrap up all the dependencies in a package.
+
+author
+------
+
+Brennen Bearnes (p1k3.com / @brennen)

chapters

@@ -1,4 +1,4 @@
-./index.md
+./introduction/index.md
 ./literary_environment/index.md
 ./literary_problem/index.md
 ./programmerthink/index.md

git-feed.pl

@@ -1,5 +1,7 @@
 #!/usr/bin/env perl
 
+# TODO: this really just ought to be a general-purpose utility
+
 use warnings;
 use strict;
 use 5.10.0;

literary_environment/index.md

@@ -58,11 +58,19 @@ incredibly powerful and expressive piece of software.
 get you a shell
 ---------------
 
-{TODO: Make this section useful.}
+Not very long ago, it was common for schools, employers, and ISPs to hand out
+shell accounts on big shared systems.  Lots of people were exposed to the
+command line as a side effect of needing to read e-mail.
+
+That doesn't happen as much as it used to, which in some ways is kind of a
+drag, but in the mean time computers have gotten a lot cheaper and there's a
+lot more free software in circulation than there used to be.
 
 twisty little passages
 ----------------------
 
+Back to what the shell _is_.
+
 Have you ever played a text-based adventure game or MUD, of the kind that
 describes a setting and takes commands for movement and so on?  Readers of a
 certain age and temperament might recognize the opening of Crowther & Woods'
@@ -84,12 +92,11 @@ _Adventure_, the great-granddaddy of text adventure games:
 
     THERE IS A BOTTLE OF WATER HERE.
 
-In much the same way, you can think of the shell as a kind of environment you
-inhabit, the same way your character might inhabit an adventure game.  Or as a
-sort of vehicle for getting around inside of computers.  The difference is that
-instead of navigating around virtual rooms and hallways with commands like
-`LOOK` and `EAST`, you navigate between directories by typing commands like
-`ls` and `cd notes`:
+You can think of the shell as a kind of environment you inhabit, in much the
+way your character inhabits an adventure game.  The difference is that instead
+of navigating around virtual rooms and hallways with commands like `LOOK` and
+`EAST`, you navigate between directories by typing commands like `ls` and `cd
+notes`:
 
     $ ls
     code  Downloads  notes  p1k3  photos  scraps  userland-book

timebinding_animals/index.md

@@ -5,8 +5,8 @@ When I was a kid, I read pretty much all of Robert A. Heinlein's Science
 Fiction (the short stories, the early novels, the late novels, everything).
 Heinlein was something of a disciple of a guy named Alfred Korzybski, who had
 built up one of those elaborate intellectual systems where the whole thing may
-be kind of cracked, but there are some useful ideas in there.  You can get a
-sense of the flavor of his work from the fact that he wrote a book called
+be kind of cracked, but there are some interesting ideas in there.  You can get
+a sense of the flavor of his work from the fact that he wrote a book called
 _Science and Sanity: An Introduction to Non-Aristotelian Systems and General
 Semantics_.
 
@@ -30,9 +30,9 @@ There's an important
 
 To cover:
 
-* heinlein
-* korzybski
-* timebinding animals
 * scripting
 * makefiles
 * memory
+* command history
+* Ctrl-R
+* version control and that sorta stuff