A book about the command line for humans.
Brennen Bearnes e0a890d255 fix publish target 5 months ago
diff link a couple of things under "get you a shell", shrink header indents 3 years ago
endmatter remove squiggle.city mention, replace github with code.p1k3.com 5 months ago
general_purpose fiddling with typography & web/ text 4 years ago
get_shell remove squiggle.city mention, replace github with code.p1k3.com 5 months ago
images add by-sa-4.png 1 year ago
introduction explicit license 4 years ago
js collapsible ToC, stub "get you a shell" section 4 years ago
literary_environment catenate 4 years ago
literary_problem fix an error trying to cat a thing that's a dir now 4 years ago
miscellany work-in-progress notice on shared space chapter 4 years ago
programmerthink fiddling with typography & web/ text 4 years ago
script random stuff 4 years ago
shared_space dmr 3 years ago
slides moar slides - final version for talk i actually gave on halloween 4 years ago
timebinding_animals actual README.md, mostly for GitHub; shuffle file layout a bit 4 years ago
web start in on a shared_space chapter 4 years ago
.gitignore .gitignore feed.xml 1 year ago
Makefile fix publish target 5 months ago
README.md remove squiggle.city mention, replace github with code.p1k3.com 5 months ago
aidan.html add aidan's timeless html contribution 1 year ago
chapters start in on a shared_space chapter 4 years ago
footer.html paste(1) 4 years ago
header.html feed in header; zap generated index.html 4 years ago
index.html remove squiggle.city mention, replace github with code.p1k3.com 5 months ago
links.md remove squiggle.city mention, replace github with code.p1k3.com 5 months ago
render.pl remove squiggle.city mention, replace github with code.p1k3.com 5 months ago
userland.css link a couple of things under "get you a shell", shrink header indents 3 years ago
wordcount.sh actual README.md, mostly for GitHub; shuffle file layout a bit 4 years ago

README.md

userland: a book about the command line for humans

This is the source for some text which can be found here:

p1k3.com/userland-book/

…which is probably the best place to read it.

what

From the introduction:

Late last year, a side trip 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.

code.p1k3.com/gitea/brennen/userland-book is the canonical git repo, for the moment. There’s also a GitHub mirror.

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)