Browse Source

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

Brennen Bearnes 4 years ago
parent
commit
8e2e295c4c
8 changed files with 100 additions and 14 deletions
  1. 0
    1
      README.md
  2. 78
    0
      README.md
  3. 1
    1
      chapters
  4. 2
    0
      git-feed.pl
  5. 0
    0
      introduction/index.md
  6. 14
    7
      literary_environment/index.md
  7. 5
    5
      timebinding_animals/index.md
  8. 0
    0
      wordcount.sh

+ 0
- 1
README.md View File

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

+ 78
- 0
README.md View File

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

+ 1
- 1
chapters View File

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

+ 2
- 0
git-feed.pl View File

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

index.md → introduction/index.md View File


+ 14
- 7
literary_environment/index.md View File

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

+ 5
- 5
timebinding_animals/index.md View File

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

+ 0
- 0
wordcount.sh View File