reorder some text

1 files changed, 124 insertions, 13 deletions

diff --git a/README.md b/README.md
index a50cfd6..10a8611 100644
--- a/README.md
+++ b/README.md
@@ -11,10 +11,11 @@ Side Part:
 :::
 
 3D printable parametric cubbies to store your 3D things. There are two distinct
-parts — a `bottom` and a `side` — that are generated to the dimensions of your
-things, then 3D printed and assembled into modular storage units. The parts are
-optimized for printing as they are made of sparse structures to save material,
-and lay flat on the print bed.
+shapes — a `bottom` and a `side` — that are generated to the dimensions of your
+things, 3D printed, then assembled into modular storage units. The parts are
+optimized for printing by using [sparse
+structures](https://github.com/revarbat/BOSL2/wiki/walls.scad#module-sparse_strut)
+(to save material) that lay flat on the print bed (for ease of printing).
 
 ## Pictures ##
 
@@ -40,23 +41,28 @@ and lay flat on the print bed.
 
 ### 🚫 Do NOT Scale in a Slicer 🚫 ###
 
-All models should be generated by specifying the parameters `cubby_width`,
-`cubby_depth`, and `cubby_height` in `cubbies.scad` (ways to do this are
-described below.) The dovetail joints are generated to a constant size
+All models should be generated by specifying, at minimum, the parameters
+`cubby_width`, `cubby_depth`, and `cubby_height` in `cubbies.scad` (ways to do
+this are described below.) The dovetail joints are generated to a constant size
 (controlled through the parameters `tab_width`, `tab_padding`, and
 `tab_tolerance`) and should not be expected to fit after being scaled. Cubbies
 can be generated in in one of the following ways:
 
   * Using the Thingiverse Customizer
 
-  * Using `Openscad` -- either by using its builtin customizer (choose
-    `Window -> Customizer` from the menu bar if it is not visible), or by
-    modifying the variables at the top of the `cubbies.scad` file.
+  * Using [OpenScad](https://openscad.org "Homepage for OpenSCAD \"The
+    Programmers Solid 3D Cad Modeller\"") -- either by using its builtin
+    customizer (choose `Window -> Customizer` from the menu bar if it is not
+    visible), or by modifying the variables at the top of the `cubbies.scad`
+    file. As mentioned above, the minimum paramaters to generate a custom sized
+    cubby are `cubby_width`, `cubby_depth`, and `cubby_height`. (Even those
+    arguments can be omitted, and your cubby will be whatever abritrary size I
+    decided as defaults (`40`,`120`,`90`).)
 
   * There are two scripts for generating cubbies from the commandline:
-    `cubbies.sh` (run `./cubbies.sh -h` for details) can generate entire sets of
-    cubbies, and `shopenscad.sh` (run `./shopenscad.sh -h` for details)
-    generates individual parts.
+    `cubbies.sh` (run [`./cubbies.sh -h` for details](#cubbies.sh) can generate
+    entire sets of cubbies, and `shopenscad.sh` (run `./shopenscad.sh -h` for
+    details[^1]) generates individual parts.
 
 For a single cubby, you will need to print the side piece twice, and the bottom
 piece once. To add additional cubbies, print one bottom and one side. The bottom
@@ -191,6 +197,106 @@ pieces).
 - Venmo: <https://venmo.com/u/Steven-Vasilogianis>
 - CashApp: <https://cash.app/$svasi>
 
+## Shell Scripts ##
+
+### cubbies.sh ###
+
+```
+$ ./cubbies.sh -h
+./cubbies.sh: generate sets of cubbies. You will need print the side piece twice for your
+first bottom piece, then a single side piece for each additional bottom piece.
+
+Usage:
+./cubbies.sh cubby-depth cubby-height cubby-width1 [cubby-width2 ... cubby-widthN]
+
+Examples:
+
+    ./cubbies.sh 150 90 20
+
+    Generates two total pieces: a side piece (150mm depth, 90mm height) and a
+    bottom piece (150mm depth and 20mm width). You will need to print the side
+    piece twice and bottom piece once.
+
+    ./cubbies.sh 180 120 20 30 35
+
+    Generates four total pieces, which can be assembled to form a row of
+    cubbies: one side piece (180mm depth, 120mm height) and three bottom pieces,
+    with widths of 20mm, 30mm, and 35mm (and each sharing the same depth of
+    180mm). The side piece will need to be printed 4 times, and each bottom
+    piece printed once.
+
+    thickness=3 strut_thickness=4 ./cubbies.sh 200 140 20
+
+    You can override any of the other variables from your scad file by passing
+    them into ./cubbies.sh in this manner.
+```
+
+### shopenscad.sh ###
+
+```
+$ ./shopenscad.sh -h
+./shopenscad.sh: parse and execute OpenSCAD files, allowing default variables from input scad
+    to be overridden with values supplied from the shell. (The parsing of scad
+    files is done from the shell mostly with sed, and is very primitive)
+
+Usage: ./shopenscad.sh [-h] [-n] [-p] [-i] [-o OUTPUT-FILENAME] INPUT.scad
+
+ -h, --help            display this help
+ -p, --print-vars      print variables parsed from INPUT.scad
+ -i, --interactive     show output command and query for execution
+ -n, --no-act          show output command, do not execute
+ -s, --shell-skel      output a skeleton shell script for generating models
+ -o, --output-filename Specify an output filename. The following variables are
+                       available to you:
+
+                       $VALUES - all values from INPUT.scad. This is the
+                                  default (-o '${VALUES}.stl'):
+                         cube-15-10-5.stl
+
+                       $ALL - all variable names and values from INPUT.scad
+                               (-o '${ALL}.stl'):
+                         shape=cube,width=15,height=10,depth=5.stl
+
+                       Additionally, all variables parsed from INPUT.scad
+                       are available in the associatve array , e.g.:
+                         -o '${SCAD[part]}.stl'
+
+Usage examples:
+
+      1) Run openscad with default values from input scad file:
+
+          $ ./shopenscad.sh input.scad
+
+      2) You can override variables in the input file with variables passed in
+         through the shell; this will override "part" and "cubby_width"
+         paramaters from input scad file. (Note that if the part is a string,
+         you need to include quotes.):
+
+          $ cubby_width=200 part='"bottom"' ./shopenscad.sh input.scad
+
+
+      3) Generate multiple models:
+
+         $ for w in 250 300 350 400; do
+               cubby_width="" part="bottom" ./shopenscad.sh  cubbies.scad
+           done
+```
+
+### test_fits.sh ###
+
+```
+$ ./test_fits.sh -h
+Usage:
+./test_fits.sh
+./test_fits.sh [depth] [tolerance1 tolerance2 .. toleranceN]
+
+By default five test fit pieces are generated with a length of 120mm at the
+tolerances 0.1mm, 0.2mm, 0.3mm, 0.4mm, and 0.5mm.
+
+Over ride the defaults by supplying paramaters; the first parameter the depth and the rest are
+taken as tolerances.
+```
+
 ## GPLv3 License ##
 
 Copyright (C) Steven Vasilogianis
@@ -200,3 +306,8 @@ the terms of the GNU General Public License as published by the Free Software
 Foundation, either version 3 of the License, or (at your option) any later
 version.
 
+[^1]: OpenSCAD already allows you to generate models with varying paramaters
+through, e.g., `OpenSCAD -D "param1=100" -D "param2=10" scadfile.scad -o
+output.stl`. Now you're going to want to change the output.stl filename to avoid
+overwriting a previously generated model; generally, the information going into
+your variables is useful to have in the output filename.