Add developer docs

- explain structure of THREAD_TABLE.scad and relation to thread module
- explain threads and how to derive proper specs for inclusion in threadlib
- explain use of autogenerate.awk
- explain tests (i.e., test_table.awk)

closes #5

docs/CreatingThreadSpecs.md

@@ -0,0 +1,137 @@
+# Creating Thread Specs
+
+In the following, we explain how a thread spec (i.e., an entry in THREAD_TABLE) is created. First, we will explain the basics of threads and how they are specified in the norms. Then, we will ellaborate on the specifics to translate those into threadlib thread specs.
+
+
+## Thread Basics
+
+
+To do this, we use British Standard Pipe parallel (BSPP) thread as an example (see drawing below). The bold curve shows the parting line between internal and external thread. In an ideal world, both threads are created according to the parting line. The parting line of BSP thread is based on a fundamental triangle with a 55-degree angle rounded to a radius r.
+
+![BSPP thread drawing](http://mdmetric.com/tech/55deg228.gif) 
+
+     BSPP thread drawing. Source: Maryland Metrics.
+
+Reality is a bit more complicated: If one of the threads deviates only a little in the wrong direction, the threads collide. Therefore, the pitch radius r_pitch (radius where distance between falling and rising edges is exactly P/2) of the external thread has to be reduced a little bit (and vice versa for the internal thread). Also, major and minor radii are adjusted so that the real thread is guaranteed to remain on its own side of the theoretical parting line.
+
+Of course, it is not ok to introduce arbitrarily large allowances: The norm (BS EN ISO 228-1: 2003 in this case) gives the necessary constraints. Quoting [Maryland Metrics thread data charts for BSP thread](http://mdmetric.com/tech/thddat7.htm): 
+
+<table>
+ <tr>
+ <td colspan="7" align="center" valign="bottom"></td>
+ <td colspan="5" align="center" valign="bottom">Tolerances on pitch diametera</td>
+ <td colspan="2" align="center" valign="bottom">Tolerance on minor diameter</td>
+ <td colspan="2" align="center" valign="bottom">Tolerance on major diameter</td>
+ </tr>
+ <tr>
+ <td colspan="4" align="center" valign="bottom"></td>
+ <td colspan="3" align="center" valign="bottom">Diameters</td>
+ <td colspan="2" align="center" valign="bottom">Internal thread TD2</td>
+ <td colspan="3" align="center" valign="bottom">External thread Td2</td>
+ <td colspan="2" align="center" valign="bottom">Internal thread TD1</td>
+ <td colspan="2" align="center" valign="bottom">External thread Td</td>
+ </tr>
+ <tr>
+ <td align="center" valign="bottom">Desig-nation of thread</td>
+ <td align="center" valign="bottom">Number of threads in 25.4 mm</td>
+ <td align="center" valign="bottom">Pitch    P</td>
+ <td align="center" valign="bottom">Height of thread    h</td>
+ <td align="center" valign="bottom">major d  = D</td>
+ <td align="center" valign="bottom">pitch d2  = D2</td>
+ <td align="center" valign="bottom">minor d1  = D1</td>
+ <td align="center" valign="bottom">Lower deviation</td>
+ <td align="center" valign="bottom">Upper deviation</td>
+ <td align="center" valign="bottom">Lower deviation Class A</td>
+ <td align="center" valign="bottom">Lower deviation Class B</td>
+ <td align="center" valign="bottom">Upper deviation</td>
+ <td align="center" valign="bottom">Lower deviation</td>
+ <td align="center" valign="bottom">Upper deviation</td>
+ <td align="center" valign="bottom">Lower deviation</td>
+ <td align="center" valign="bottom">Upper deviation</td>
+ </tr>
+ <tr>
+ <td align="center" valign="bottom">1/16</td>
+ <td align="center" valign="bottom">28</td>
+ <td align="center" valign="bottom">0.907</td>
+ <td align="center" valign="bottom">0.581</td>
+ <td align="center" valign="bottom">7.723</td>
+ <td align="center" valign="bottom">7.142</td>
+ <td align="center" valign="bottom">6.561</td>
+ <td align="center" valign="bottom">0</td>
+ <td align="center" valign="bottom">0.107</td>
+ <td align="center" valign="bottom">-0.107</td>
+ <td align="center" valign="bottom">-0.214</td>
+ <td align="center" valign="bottom">0</td>
+ <td align="center" valign="bottom">0</td>
+ <td align="center" valign="bottom">0.282</td>
+ <td align="center" valign="bottom">-0.214</td>
+ <td align="center" valign="bottom">0</td>
+ </tr>
+ <tr>
+ <td align="center" valign="bottom">1/8</td>
+ <td align="center" valign="bottom">28</td>
+ <td align="center" valign="bottom">0.907</td>
+ <td align="center" valign="bottom">0.581</td>
+ <td align="center" valign="bottom">9.728</td>
+ <td align="center" valign="bottom">9.147</td>
+ <td align="center" valign="bottom">8.566</td>
+ <td align="center" valign="bottom">0</td>
+ <td align="center" valign="bottom">0.107</td>
+ <td align="center" valign="bottom">-0.107</td>
+ <td align="center" valign="bottom">-0.214</td>
+ <td align="center" valign="bottom">0</td>
+ <td align="center" valign="bottom">0</td>
+ <td align="center" valign="bottom">0.282</td>
+ <td align="center" valign="bottom">-0.214</td>
+ <td align="center" valign="bottom">0</td>
+ </tr>
+ <tr>
+ <td align="center" valign="bottom">1/4</td>
+ <td align="center" valign="bottom">19</td>
+ <td align="center" valign="bottom">1.337</td>
+ <td align="center" valign="bottom">0.856</td>
+ <td align="center" valign="bottom">13.157</td>
+ <td align="center" valign="bottom">12.301</td>
+ <td align="center" valign="bottom">11.445</td>
+ <td align="center" valign="bottom">0</td>
+ <td align="center" valign="bottom">0.125</td>
+ <td align="center" valign="bottom">-0.125</td>
+ <td align="center" valign="bottom">-0.25</td>
+ <td align="center" valign="bottom">0</td>
+ <td align="center" valign="bottom">0</td>
+ <td align="center" valign="bottom">0.445</td>
+ <td align="center" valign="bottom">-0.25</td>
+ <td align="center" valign="bottom">0</td>
+ </tr>
+</table>
+
+
+## Deriving threadlib Specs
+
+To simplify the thread profile, we want to avoid the rounding and replace it by a trapezoidal edge as shown in here (red: internal, blue external thread): 
+
+![threadlib profile compared to BSP parting line](imgs/BSPthread.jpg)
+ 
+It is clear that we have to match the pitch as accurately as possible.  Therefore, threadlibs P is equal to the pitch in the norm (for G1/16: 0.907 mm).
+
+Then, we choose the pitch diameter to be in the center of the given tolerance range. For G1/16 this is (7.723 + 0.107/2) mm. 
+
+To explain the choice of r_major and r_minor for both external and internal threads simultaneously, we use the terms r_crest and r_valley. r_crest is the major/minor radius (external/internal) and r_valley is the minor/major radius (external/internal). The norm does not give limits for r_valley. But threadlib requires that the threadprofile covers *less* than 1 pitch of thread. Therefore, we arbitrarily choose a small but finite width of "valley floor" that leaves ample clearance to the parting line. For r_crest, we to take into account
+
+a) the allowed deviations given in the norm
+b) the rounding (that we want to leave away)
+
+The former is simple: We aim for the center. The latter requires a little math: We want our piecewise linear profile to remain on one side of the (true) BSP profile. Therefore, our crest radius has to be equal to the radius where the straight rising edge of the BSP profile touches the circle of the rounding.
+
+
+## Adding Specs to threadlib
+
+To get the threads into threadlib, we currently do the following (attention: will change in the near future to avoid Excel file): 
+
+- Add worksheet with original thread specs to design/threads.xlsx
+- Extend table in worksheet THREAD_TABLE (calculate threadlib specs from your original specs)
+- Save THREAD_TABLE worksheet as THREAD_TABLE.csv
+- Do `cat THREAD_TABLE.csv | awk -f design/autogenerate.awk > THREAD_TABLE.scad` in a terminal
+
+Furthermore, we should extend tests/test_table.awk to test our newly created threads. The very minimum is to add a test for the thread angles. Perform the tests by running `make` inside the tests subdirectory. If it prints "TESTS SUCCESSFUL" you are probably fine. Note: If you have a thread spec that is not tested at all, the tests will fail, too.
+

docs/DesignOfThreadlib.md

@@ -0,0 +1,52 @@
+# Design of threadlib
+
+The structure of threadlib is very simple and consists of only two files:
+
+- threadlib.scad
+- THREAD_TABLE.scad
+
+The former provides the code to generate threads, bolts, and nuts. The latter simply holds a large dictionary (named THREAD_TABLE) providing the thread-specs given a thread-designator.
+
+THREAD_TABLE is a vector of vectors called "entries". Every entry has the following format:
+
+
+    [DESIGNATOR, [P, Rrot, Dsup, profile]]
+
+where
+
+- DESIGNATOR: Name of thread. E.g. "M6x0.5-ext"
+- P: Pitch of the thread
+- Rrot: Radius of rotation used for later "extrusion" of the thread. Rrot is positive for external threads and negative for internal threads.
+- Dsup: Recommended diameter of support structure of the thread (i.e., of cylinder for external thread and hole for internal thread)
+- profile: A vector of 2D [delta_r, z]-vectors describing the shape of the thread
+
+Let's look at an example:
+
+    ["M4-int", [0.7, -2.1095, 4.1095,
+                [
+                 [0, 0.3465], 
+                 [0, -0.3465], 
+                 [0.43304671, -0.09648036], 
+                 [0.43304671, 0.09648036]
+                ]]]
+
+
+## Definition of profile
+
+profile is a list of vectors in OpenSCADs x-y plane. x corresponds to the radial direction of the screw, z is the axis of the threads helix.
+
+![Thread Profile](imgs/ThreadProfile.png)
+
+In many cases, profile consists of 4 points. However, the number of points is not limited: You can use as many as you need. For external threads, the profile is specified in the right-hand side of the x-y plane. For internal threads, the left-hand side is used (i.e., the radius-values are negative). This is useful to make corresponding male and female threads match without extra operations: The female thread has rotated by half a turn when it arrives on the right-hand side of the x-y plane, thereby nicely fitting in between two turns of the male thread.
+
+
+## Redundancy?
+
+Why do we need P, Rrot, Dsup, *and* profile? Can we not include everything in profile? Unfortunately, we can't. The reasons are a) lead-in / lead-out tapers ("lilo-tapers") and b) overlap between thread and support to avoid rendering problems.
+
+*lilo-tapers*: To make the tapers, the profile is scaled-down at the ends. We need to know where the profile is scaled to (center of scaling). We solve this by specifying the radius of rotation for extrusion Rrot explicitly and subtract it from profile (profile holds [dr, z] instead of [r, z]). lilo-tapers are then created by scaling towards dr=0.
+
+*Overlap 1*: We could include P in profile by requiring that profile extends over exactly one period (i.e., P). However, this would result in a helix where neighbouring periods would exactly touch each other. This leads to rendering artifacts => P is stored seperately and profile is *required* to cover *less* than a period. 
+
+*Overlap 2*: But hey! Dsup = 2 * Rrot, no? In principle yes, but in that case thread and bolt would *just* touch => rendering problems. But we could implicitly assume that Rrot is simply 1% smaller than Dsup / 2 for external threads (and 1% larger for internal threads)! Yes, we could. But we decided to make that choice explicit rather than implicit.
+

docs/UnitTests.md

@@ -0,0 +1,61 @@
+# Unit Tests
+
+We use unit tests as a means of quality assurance for threadlib.
+
+
+## THREAD_TABLE.scad
+
+The thread table is tested using an awk script. See [The GNU Awk User's Guide](https://www.gnu.org/software/gawk/manual/gawk.html) for (more than) an introduction to awk. Note that development of threadlib is based not on GNU awk but on MacOSs version of awk, which is mostly - but not completely - compatible.
+
+Every line of THREAD_TABLE.scad is fed to [tests/test_table.awk](../tests/test_table.awk). test_table.awk then runs appropriate tests for every line. Which tests are appropriate are determined by looking at the thread designator. For example:
+
+	/"[^,]+-ext/ {
+		# external threads have positive Rrot 
+		parse();
+		if (Rrot < 0) {
+			print designator " FAIL: negative radius of rotation";
+			PASS = 0;
+		}
+		# test overlapp between thread and support
+		if (Rrot > Dsupport / 2) {
+			print designator " FAIL: Rsupport < Rrot";
+			PASS = 0;
+		}
+	}
+
+The pattern /"[^,]+-ext/ means: Run this code for every line that contains double quotes followed by a non-zero (+) number of non-comma characters ([^,]) followed by the string "-ext". I.e, the code is run for every external thread.  The code (everything between {}) tests the following assumptions: 1. every external thread must have positive Rrot 2. there must be some overlap between thread and support (i.e. Rrot > Dsupport / 2).
+
+More specific tests verify, e.g., that the thread angles are correct. Not all threads have the same thread angles, therefore we have to distinguish, e.g., between metric threads (designator "M...") and BSPP threads (designator "G..."). Example:
+
+	/M[0-9.x-]+-ext/ {
+		# ext M threads have +/-60 deg slopes, horizontal crest / valley
+		parse();
+		m1 = slope(v0, v3) / deg;
+		m2 = slope(v2, v1) / deg;
+		if (m1 > 60 + dphi || m1 < 60 - dphi \
+		    || m2 < -60 - dphi || m2 > -60 + dphi) {
+			print designator " FAIL: " m1 ", " m2 " deg";
+			PASS = 0;
+		};
+		test_horizontal();
+		tested = 1;
+	}
+
+Note that:
+
+- This test uses functions. These are defined at the top of the awk script.
+- This test will run *in addition* to the more general test discussed above. It does not *replace* the previous test.
+
+Furthermore, we track whether tests fail. This is done in 2 ways:
+
+- If a test fails it prints an error to the screen
+- If a test fails the variable PASS is set to zero
+
+At the very end (END {...}), the awk script tests the value of PASS. If all tests were successfull, it still has its initial value of 1 (set in the BEGIN {...} block). Otherwise, it is 0.
+
+Finally, we have assured that every thread is tested. A thread that is not tested at all is considered a FAIL. This is done via two match-all rules: The first initialized the variable 'tested' to 0. The last verifies that it has been set to 1 by one of the test. If it is still zero, this particular thread has not been tested at all.
+
+## threadlib.scad
+
+We intend to add tests for threadlib.scad itself. E.g. by actually rendering a pair of external and internal threads and verifying the number of volumes created. Currently, we do not have these tests yet.
+