diff options
Diffstat (limited to 'docs/projects')
| -rw-r--r-- | docs/projects/bash-workshop.md | 340 | ||||
| -rw-r--r-- | docs/projects/img/bash-workshop/average_familiarity.png | bin | 0 -> 35986 bytes | |||
| -rw-r--r-- | docs/projects/img/bash-workshop/bash_history.png | bin | 0 -> 58917 bytes | |||
| -rw-r--r-- | docs/projects/img/bash-workshop/cheatsheet.png | bin | 0 -> 79696 bytes | |||
| -rw-r--r-- | docs/projects/img/bash-workshop/cli_challenge.png | bin | 0 -> 54397 bytes | |||
| -rw-r--r-- | docs/projects/img/bash-workshop/environment_variables.png | bin | 0 -> 72233 bytes | |||
| -rw-r--r-- | docs/projects/img/bash-workshop/navbar.png | bin | 0 -> 2748 bytes | |||
| -rw-r--r-- | docs/projects/img/bash-workshop/rickroll.png | bin | 0 -> 165868 bytes | |||
| -rw-r--r-- | docs/projects/img/bash-workshop/ultimate_challenge.png | bin | 0 -> 68703 bytes | |||
| -rw-r--r-- | docs/projects/img/bash-workshop/wechat.png | bin | 0 -> 67742 bytes | |||
| -rw-r--r-- | docs/projects/img/bash-workshop/workshop.jpg | bin | 0 -> 1715267 bytes |
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>. + + + +▲ 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 + + + +▲ 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 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. + + + +▲ 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. + + + +▲ I spent 6 RMB on 30 copies. 13 were handed out on site. + +### Easter eggs + + + +▲ 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> + + + +▲ 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> + +</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.) + + + +▲ 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; + + + +▲ [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 Binary files differnew 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 Binary files differnew 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 Binary files differnew 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 Binary files differnew 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 Binary files differnew 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 Binary files differnew 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 Binary files differnew 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 Binary files differnew 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 Binary files differnew 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 Binary files differnew file mode 100644 index 0000000..b3a6432 --- /dev/null +++ b/docs/projects/img/bash-workshop/workshop.jpg |
