From a7da48e7ecc4fc7dc92d64597a9cb04908c96a63 Mon Sep 17 00:00:00 2001
From: Connor Olding <cloningdonor@gmail.com>
Date: Fri, 23 Sep 2022 12:22:51 -0700
Subject: [PATCH] refine code style section

---
 README.md | 22 +++++++++++++---------
 1 file changed, 13 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 33ea7f1..95c21a9 100644
--- a/README.md
+++ b/README.md
@@ -64,7 +64,7 @@ RUN : \
 ;
 ```
 
-*gratuitous explanation:*
+#### gratuitous explanation
 
   * 4-space indentation is a must, since at least three characters
     are needed to contain the operators on the left of each line.
@@ -72,9 +72,8 @@ RUN : \
   * `:` is akin to the `true` command; it's used as a no-op
     that only sets the most recent exit code (`$?`) to `0`.
 
-  * `\` continues the code to the next line;
+  * `\` continues the shell command to the next line;
     the proceeding newline is removed and ignored.
-    this is purely superficial.
 
   * `&&` is a short-circuiting operator that only evaluates
     its right-hand side when `$?` is `0`. `&&` is preferred
@@ -82,17 +81,22 @@ RUN : \
     non-zero exit code to indicate that an error occurred,
     whereas `;` will continue executing code,
     even in the presence of an error.
+    **note:** the `diff` command breaks the convention
+    and uses both `0` and `1` as normal exit codes.
 
   * `||` is like `&&` but only executes when `$?` is *not* `0`.
     **important:** `||` has a lower precedence than `&&`!
     make sure to wrap your `||`s in braces unless you want to
-    capture *everything* before it. for instance:  
+    capture *everything* before it. for example, an excerpt
+    of a shell script might look like this:  
     ` && { test -e myfile || touch myfile ;} \`
 
   * leftmost `&&`s and `||`s are always centered within their 4-space indent.
 
   * avoid using pipes (`|`) when possible, because only the
     exit code of the final command in any pipe is respected.
+    instead, write intermediate data to `/tmp` when possible.
+    remember to mount `/tmp` as a `tmpfs` at the start of the `RUN` command!
 
   * functions are declared (`()`) on their own line
     without any braces or other commands.
@@ -101,22 +105,22 @@ RUN : \
     similar to how `RUN :` begins a shell command.
     sadly, the space between the brace and the colon is not optional.
 
-  * ';}` is used to finish a multi-line block.
+  * `;}` is used to finish a multi-line block.
     this is aligned with the preceeding `&&` and `||` operators.
     thankfully, the space between `;` and `}` is optional.
 
   * a final `;` is used to finish off the line-continutation.
     this means that every line before it can end with a `\`,
     which simplifies editing. when podman gives you strange errors,
-    double-check that you aren't forgetting the final semicolon.
+    double-check that you aren't forgetting a `\` or the final semicolon.
 
   * redirections are usually specified *before* a final list of arguments.
     this makes skimming code easier when arguments extend across many lines.
 
-  * **TODO:** explain `if cmd ␤ ;then : ␤ ;fi`.
+  * **TODO:** explain `if cmd \␤ ;then : \␤ && cmd \␤ ;fi`.
 
-  * **TODO:** explain `for cmd ␤ ;do : ␤ ;done`.
+  * **TODO:** explain `for cmd \␤ ;do : \␤ && cmd \␤ ;done`.
 
-  * **TODO:** explain `while cmd ␤ ;do : ␤ ;done`.
+  * **TODO:** explain `while cmd \␤ ;do : \␤ && cmd \␤ ;done`.
 
   * **TODO:** explain `test`s.