rewrite introduction

Makefile

@@ -10,6 +10,7 @@ articles != find * -type f -name "*.md"
 
 db.rec: $(articles)
 	printf '%s\n' '%rec: guide' > $@
+	printf '%s\n' '%type: wordcount int' >> $@
 	printf '%s\n\n' '%sort: title' >> $@
 	for x in $^ ; do \
 		sed -n '2,/^---$$/ {/^---$$/d; p}' "$$x" |\
@@ -17,6 +18,9 @@ db.rec: $(articles)
 		tr -d '"' ;\
 		printf "file: %s\n\n" "$$x" ;\
 	done >> $@
+	for entry in $^; do \
+		recset $@ -e "file = '$${entry}'" -f wordcount --set-add="$$(wc -w < $${entry})" ;\
+	done
 	recsel $@ -e "requires != ''" -CR title,requires |\
 	while read title requires; do \
 		IFS=', ' && for provider in $$requires; do \
@@ -33,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

README.md

@@ -1,77 +1,67 @@
 ---
-title: "Knowledge Base"
+title: "Linux Knowledge Base"
 ---
 
-# Linux Knowledgebase
+The Linux Knowledge-Base provides quick-start guides for working with terminal programs.
 
-This is a list of quickstart guides for Linux programs, designed to get the user up and running as fast as possible.
+# 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,12 +69,14 @@ ss -tr dst :$PORT
 - Often presumes you know everything except that one program.
 - Often written in the 80's, and it shows.
 - 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.
 - Poor understanding of priority (`git stash` is covered before `git commit`).
+- Repetitive
 
 # Current State