Browse Source

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

pull/1/head
Brennen Bearnes 7 years ago
parent
commit
8e2e295c4c
7 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 @@
index.md

+ 78
- 0
README.md View File

@ -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)

+ 1
- 1
chapters View File

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


+ 2
- 0
git-feed.pl View File

@ -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;


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.
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


+ 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
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

+ 0
- 0
wordcount.sh View File


Loading…
Cancel
Save