From 9621cfc26a4c397e7b3425276891c04b2fb8b405 Mon Sep 17 00:00:00 2001
From: Malin Freeborn <malinfreeborn@posteo.net>
Date: Tue, 11 Feb 2025 20:39:24 +0100
Subject: [PATCH] rewrite introduction

---
 Makefile  |  2 +-
 README.md | 88 +++++++++++++++++++++++++------------------------------
 2 files changed, 41 insertions(+), 49 deletions(-)

diff --git a/Makefile b/Makefile
index c9e731d..5eefb86 100644
--- a/Makefile
+++ b/Makefile
@@ -37,7 +37,7 @@ default += db.rec
 default += .git/info/exclude
 
 .PHONY: database
-database: $(default) ## Make a database for recfiles
+database: $(default) ## Make a recfiles database
 
 .PHONY: article
 article: ## Write an article
diff --git a/README.md b/README.md
index 4ed35a6..99ce3df 100644
--- a/README.md
+++ b/README.md
@@ -4,72 +4,64 @@ title: "Linux Knowledge Base"
 
 The Linux Knowledge-Base provides quick-start guides for working with terminal programs.
 
+# Setup
+
+Install `make`, `recutils`, and any fuzzy-finder (i.e. `sk`, `fzy`, or `fzf`).
+
+Usage: `make`
+
 # Style
 
-## Praxis Only
+## No History, No Context
 
-We leave theory alone as much as possible.
-The documentation should be of the form 'if you want *X*, type *Y*'.
+- Nobody cares about how the project started.
+- Nobody wants to read what `ffmpeg` is, because anyone who wants to use it already knows what it is.
 
-We don't need to explain what a program does - anyone looking up 'how to X', already knows what they want to do.
-We don't even need to explain which program to use - if someone wants to combine an mp4 and webm video into a single video file, they only care about that result, not about learning `ffmpeg`.
+## Be Opinionated
 
-Any interest in these tools only comes after we can use them.
+- Guides should not ask the reader to select options half-way through.
+- Options for different filesystems, databases, et c., should be written as separate guides.
 
-## Chronological
+## Repetition Beats Reference
 
-Entries should read like scripts - everything in the right order, with small notes on what this does.
+If a database requires three commands to set up, it's better to repeat those three commands for every program that requires a database than to just link to another file which discusses databases.
 
-The chronology should never branch.
-If `gitea` can use three different types of database, the documentation should simply pick one and continue instructions from there.
-Repetition works better than a reference - if a database requires three commands to set up, it's better to repeat those three commands for every program that requires a database than to just link to another file which discusses databases.
+## Show Arguments as Variables
 
----
+Look at this line:
 
-### Closing
-
-Introductory documents should show anything required to cleanly uninstall a program, without leaving bulky configuration files behind.
-
-## Three Input Types
-
-There are three types of examples:
-
-Fixed input:
-
-```bash
-ls
+```sh
+grep ls --color=always  $HISTFILE | less -R
 ```
 
-Anything with arbitrary input should be shown as a variable.
+What else can go in place of `always`?
+Can you say `--color=red`?
+Can you put anything?
+The answer is not obvious.
 
-```bash
-ls $FILE
+What about this line:
+
+```sh
+git branch new
+git checkout new
 ```
 
-Non-commands (e.g. output) should be shown as quoted text:
+Do you always use `new`?
+Can you use another word here?
+The answer is not obvious.
 
-> LK           img
-> Mail         kn
-> Projects     music
-
----
-
-# Example
-
-```
-How to see which websites you're actively accessing:
-
-` ` `bash
-ss -tr dst :$PORT
-` ` `   
-
-> State  Recv-Q  Send-Q   Local Address:Port     Peer Address:Port   Process  
-> ESTAB  0       0         192.168.0.14:42476  149.154.167.91:https           
-> ESTAB  0       0         192.168.0.14:43644   104.17.90.199:https           
+It's better to make all arbitrary values variables.
 
+```sh
+git branch $branch_name
+git checkout $branch_name
+PAGER='less -R'
+grep ls --color=always $HISTFILE | $PAGER
 ```
 
-# What's wrong with everything else?
+Now we can see what can be changed.
+
+# What's Wrong with Everything Else?
 
 ## Man pages
 
@@ -79,7 +71,7 @@ ss -tr dst :$PORT
 - Zero respect for your time.
 - Often references `info` pages (yuck).
 
-## curl cheat.sh/
+## `curl cheat.sh`
 
 - Doesn't have the programs I like.
 - Too short to get you started on many programs.