New post: project/bash-workshop

11 files changed, 340 insertions, 0 deletions

diff --git a/docs/projects/bash-workshop.md b/docs/projects/bash-workshop.md
new file mode 100644
index 0000000..2a936af
--- /dev/null
+++ b/docs/projects/bash-workshop.md
@@ -0,0 +1,340 @@
+# bash workshop
+
+2023-03-09
+
+On two consecutive Sunday evenings (2023-02-26 and 2023-03-05) I hosted
+the bash workshop on behalf of <abbr title="tech department under JI
+student union">TechJI</abbr>.
+
+![I am standing in front of a projector screen in an
+auditorium](img/bash-workshop/workshop.jpg)
+
+▲ Me delivering the talky part of the workshop
+
+## Topics
+
+Despite its name, much of this workshop is not about bash alone, but other
+tools as well. Here is a brief list:
+
+### Part 1
+
+- Intro
+    * Brief history
+    * Unix philosophy
+- Files & File Tree
+    * `cat, cp, mv, rm`
+    * `cd, pwd, ls, mkdir`
+    * Paths, `.`, `..`, `*`
+- CLI
+    * Options and arguments
+    * Reading man pages
+    * Keyboard shortcuts
+- Pipes
+    * stdin, stdout
+    * `>` and `>>`
+    * Pipes
+    * `grep`
+
+### Part 2
+
+- Regex (ERE)
+    * Patterns
+    * `grep -E`
+    * `sed -E 's///'`
+    * Capturing groups
+- Scripting
+    * Variables
+    * `if`
+    * `for`
+
+## Goal
+
+I've been on Linux for 5 years. It would be a shame if I kept all that
+bash knowledge to myself. I believe bash is something that every
+computer-related major student should know, for the following reasons:
+
+1. Efficiency. Bash has saved hours if not days of my time and will save
+   yours as well.
+
+2. Portability. Literally every server you may ssh into will have a shell
+   of some sort, and having a hint of how it works will surely help.
+
+Therefore, the aim of bash workshop is
+
+1. Learn commands/scripts/tricks to boost efficiency
+
+2. Make the most out of GNU coreutils and a few common tools you'd find
+   anywhere
+
+## Materials used
+
+- Slides (2x, ~50 pages each totalling 1.5k lines of LaTeX)
+- Cheatsheet (A4 sheet handed out on site)
+- Tarball (Follow-along examples and DIY materials)
+
+Participants were asked to download a zip file containing all three.
+
+## Design
+
+Work began in October 2022. I scraped together all the topics I feel
+confident sharing with others, and then kicked out what I felt wasn't
+common enough. For example `tr` and `cut`.
+
+In November 2022 I approached Prof. Manuel Charlemagne with an early draft
+to ask if he had any advice. The draft was not yet split in half; it was
+a 71-page giant mess. His advice was to
+
+- Pack less in one workshop
+- Create fun activities to engage participants
+- Remove that distracting navbar on the bottom
+
+![A bar of buttons](img/bash-workshop/navbar.png)
+
+▲ Navbar in the default LaTeX beamer theme
+
+I decided that the workshop should follow a practicality-first approach,
+so I filled the slides with examples that's like, "yeah you'll have to
+figure this out sooner or later, so I'll show you how right now".
+
+![Slide screenshot](img/bash-workshop/environment_variables.png)
+
+▲ Slide in section 5, "Bash Scripting"
+
+<details markdown="1">
+<summary>Transcript</summary>
+Environment variables
+
+Let's say you're downloading something from a completely legal website,
+and you want the traffic to go through your completely legal local proxy
+for completely legal reasons.
+
+```
+# set environment variable for local proxy
+$ export HTTPS_PROXY=http://localhost:8080/
+# download the thing
+$ curl -O https://legal.website/legal-thing
+```
+</details>
+
+I also designed DIY sessions at the end of each section where I ask every
+participant to run some commands, design a regex, write a script, etc.
+
+![Slide screenshot](img/bash-workshop/cli_challenge.png)
+
+▲ Challenge session at the end of section 2, "CLI"
+
+<details markdown="1">
+<summary>Transcript</summary>
+Challenge
+
+- Read the man page for head
+- Experiment with files in `02-cli/`
+- Find a command to generate the following:
+
+```
+==> p0.txt <==
+MANIFESTO OF THE COMMUNIST PARTY.
+==> p1.txt <==
+I. BOURGEOIS AND PROLETARIANS.
+```
+
+Solution
+
+```
+$ head -n1 -v p0.txt p1.txt
+```
+</details>
+
+By the way, the navbar can be removed with
+
+```
+\setbeamertemplate{navigation symbols}{}
+```
+
+### Cheatsheet
+
+The cheatsheet is a compilation of commands, regexes and syntax I covered.
+
+![Part of cheatsheet](img/bash-workshop/cheatsheet.png)
+
+▲ I spent 6 RMB on 30 copies. 13 were handed out on site.
+
+### Easter eggs
+
+![Slide screenshot](img/bash-workshop/bash_history.png)
+
+▲ On top of practicality I tried my best to sprinkle some humor.
+
+<details markdown="1">
+<summary>Transcript</summary>
+A brief history of bash
+
+- Born: 1989
+- Probably played Pokémon on the Game Boy
+- Is an umbrella term for zsh, fish, …
+- Runs on Unix-like environments
+</details>
+
+![Slide screenshot](img/bash-workshop/ultimate_challenge.png)
+
+▲ The final DIY challenge at the very end
+
+<details markdown="1">
+<summary>Transcript</summary>
+The Ultimate Challenge
+
+Each line in `05-scripting/obf.txt` begins with an 8-digit number.
+Print every line with its number greater than any of the lines above.
+
+```
+IFS=$'\n'
+max=0
+for line in $(cat obf.txt); do
+    num=$(echo $line | grep -oE '^[0-9]{8}')
+    if [[ $num -gt $max ]]; then
+        echo $line
+        max=$num
+    fi
+done
+```
+</details>
+
+Now, with so much said and done, be prepared for the best trolling in
+TechJI's history.
+
+<details markdown="1">
+<summary>You probably won't be surprised…</summary>
+![ASCII art of Rick Astley](img/bash-workshop/rickroll.png)
+</details>
+
+## Advertising
+
+We needed to advertise our event to get people to come. I wrote the first
+draft on 2023-02-16, which begins with the place, time, topics and
+prerequisites, followed by the actual marketing.
+
+I ask readers to imagine themselves as an intern who received a message
+from their boss:
+
+"And here's some simpler work for you… ssh into the server, backup the
+logs in `/var/log`, and grep the error codes generated within one minute
+past each hour, then deduplicate them and…"
+
+The intern panics, for they never touched bash other than the bare minimum
+to pass <abbr title="CS intro course">VG151</abbr>. Panic turns into
+regret — that they failed to show up on our workshop.
+
+And thus the manipulation is done; reader is brainwashed to participate.
+
+(No, of course they aren't.)
+
+![Bash workshop: A Quarter Century of Unix](img/bash-workshop/wechat.png)
+
+▲ Header banner of WeChat article
+
+Two more revisions finalized the article on 2023-02-22. My venue
+reservation was approved the next day, but not yet confirmed via email, so
+I delayed posting.
+
+By Saturday, 2023-02-25, I realized it was Too Fucking Late™ and urgently
+sent the article anyway. However I was told we can't because WeChat limits
+our account to only one batch of articles each day, and it's already out
+there.
+
+(TechJI used to have its own account, but after some reformation all
+departments share one account, JISU.)
+
+This means we have to advertise for a Sunday event — on Sunday. The
+article dropped at 10 o'clock.
+
+Lesson learned: never pretend to play safe when you hear the clock
+ticking.
+
+## How it went
+
+### Attendance
+
+\# of participants who showed up in person are 10 and 4, respectively, for
+the two parts.
+
+4 was a bit low but given the abundance of competing events that night
+(there was an art festival and a guitar concert which, had there been no
+bash workshop, I would be vibing to). However, this meant a high
+attention-per-person.
+
+### Timing
+
+Part 1 lasted around 1.5 hr; part 2 lasted 2.5. Part of the 2.5 was
+troubleshooting one by one.
+
+In retrospect I should have kicked out `sed` and capturing groups. This
+will eliminate one DIY session which I admit is a bit overwhelming for
+those who heard the word "regex" for the first time.
+
+### Unexpected technical problems
+
+- Accessing WSL filesystem might be tricky in Windows
+- One person trapped themselves in vim
+- bash refuses to execute scripts with `\r\n` linebreaks
+- On MacBooks, the default bash is FreeBSD flavor and parses `{01..05}` as
+  `{1..5}`
+
+## Reflection
+
+Here is a list of things I will fix if I were to do it again.
+
+I will test the scripts on macOS;
+
+I will prepare the promotional article sooner so it gets published at
+least three days before the event, not nine hours;
+
+I will recap the conventions from part 1 so they don't confuse
+participants in part 2;
+
+![edited xkcd](img/bash-workshop/average_familiarity.png)
+
+▲ [Original: "Average Familiarity"](https://xkcd.com/2501/)
+
+<details markdown="1">
+<summary>Transcript</summary>
+Two stick figures have a conversation.
+
+"The command line is second nature to us Linux users, so it's easy to
+forget that the average person probably only knows how to use coreutils
+and one or two regexes."
+
+"And tar cvf of course."
+
+"Of course."
+
+Caption: Even when they're trying to compensate for it, experts in
+anything wildly overestimate the average person's familiarity with their
+field.
+</details>
+
+I will clarify where participants should `cd` into before they run
+commands;
+
+I will emphasize the difference between:
+
+- `var` and `$var`
+- `echo $str` and `cat file`
+- `echo $str | COMMAND` and `COMMAND $str`
+
+## Conclusion
+
+If workshops were children this would be my firstborn. To build a workshop
+from scratch is gratifying, especially when the topic is an extract of my
+five years of experience. I would like to thank Prof. Manuel Charlemagne;
+the feedback was very useful.
+
+I learned how to weigh things — to tell things that matter from those that
+don't — and how to make it worth the time for both friends and strangers.
+
+However, I need to rework my strategy toward event preparation. I should
+have pushed forward more aggressively. Few problems are worse than running
+out of time. There was no need to play safe.
+
+```
+$ ~ exit
+```
diff --git a/docs/projects/img/bash-workshop/average_familiarity.png b/docs/projects/img/bash-workshop/average_familiarity.png
new file mode 100644
index 0000000..8b2c772
--- /dev/null
+++ b/docs/projects/img/bash-workshop/average_familiarity.png
diff --git a/docs/projects/img/bash-workshop/bash_history.png b/docs/projects/img/bash-workshop/bash_history.png
new file mode 100644
index 0000000..4233fa6
--- /dev/null
+++ b/docs/projects/img/bash-workshop/bash_history.png
diff --git a/docs/projects/img/bash-workshop/cheatsheet.png b/docs/projects/img/bash-workshop/cheatsheet.png
new file mode 100644
index 0000000..589f941
--- /dev/null
+++ b/docs/projects/img/bash-workshop/cheatsheet.png
diff --git a/docs/projects/img/bash-workshop/cli_challenge.png b/docs/projects/img/bash-workshop/cli_challenge.png
new file mode 100644
index 0000000..ff251ee
--- /dev/null
+++ b/docs/projects/img/bash-workshop/cli_challenge.png
diff --git a/docs/projects/img/bash-workshop/environment_variables.png b/docs/projects/img/bash-workshop/environment_variables.png
new file mode 100644
index 0000000..0f4b488
--- /dev/null
+++ b/docs/projects/img/bash-workshop/environment_variables.png
diff --git a/docs/projects/img/bash-workshop/navbar.png b/docs/projects/img/bash-workshop/navbar.png
new file mode 100644
index 0000000..5c434e6
--- /dev/null
+++ b/docs/projects/img/bash-workshop/navbar.png
diff --git a/docs/projects/img/bash-workshop/rickroll.png b/docs/projects/img/bash-workshop/rickroll.png
new file mode 100644
index 0000000..a418e6f
--- /dev/null
+++ b/docs/projects/img/bash-workshop/rickroll.png
diff --git a/docs/projects/img/bash-workshop/ultimate_challenge.png b/docs/projects/img/bash-workshop/ultimate_challenge.png
new file mode 100644
index 0000000..344fcd6
--- /dev/null
+++ b/docs/projects/img/bash-workshop/ultimate_challenge.png
diff --git a/docs/projects/img/bash-workshop/wechat.png b/docs/projects/img/bash-workshop/wechat.png
new file mode 100644
index 0000000..1ef1cf7
--- /dev/null
+++ b/docs/projects/img/bash-workshop/wechat.png
diff --git a/docs/projects/img/bash-workshop/workshop.jpg b/docs/projects/img/bash-workshop/workshop.jpg
new file mode 100644
index 0000000..b3a6432
--- /dev/null
+++ b/docs/projects/img/bash-workshop/workshop.jpg