a technical notebook
Brennen Bearnes 19b64f4b3c whoops - remove copy.sh 2 years ago
entries moving 2 years ago
images throckmorton 4 years ago
js collapsible ToC, stub "get you a shell" section 4 years ago
.exrc zap userland-specific stuff, add intro + a couple entries 3 years ago
Makefile reorganize things into date-based entries 3 years ago
README.md zap userland-specific stuff, add intro + a couple entries 3 years ago
context.md notes on listusers / squigglecity org 3 years ago
footer.html contents: numbered list & shown by default 3 years ago
header.html zap userland-specific stuff, add intro + a couple entries 3 years ago
index.html whoops - remove copy.sh 2 years ago
render.pl ras pi; autolinking 3 years ago
scratch reorganize things into date-based entries 3 years ago
wordcount it was totally the card reader on my laptop 3 years ago
workings.css underline more links 3 years ago

README.md

workings: a technical notebook

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

http://squiggle.city/~brennen/workings-book/

…which is probably the best place to read it.

what

I attempt to keep a notebook about the technical problems I encounter and solve (or attempt to solve), the research I conduct along the way, and the patterns or general principles I try to extract from my work.

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)