Development Docs (#58)

Improved development docs and link to it from README.

README.rst

@@ -69,6 +69,7 @@ Your libraries folder should now look similar to this:
     ├── thread_profile.scad
     └── threadlib/
 
+
 Usage
 ===========================
 
@@ -188,7 +189,10 @@ add your own:
 
 Care to share? Safe others from repeating the valuable work you have already
 accomplished and get the fame you deserve: Send in your tried and tested threads
-for addition to threadlib!
+for addition to threadlib! See `Design of Threadlib <./docs/DesignOfThreadlib.md>`_
+for help on how to hack your own thread as shown above and
+`Creating Thread Specs <./docs/CreatingThreadSpecs.md>`_ for an introduction on how
+to contribute entire thread classes to threadlib.
 
 
 Change Log

docs/BSPPthread.md

@@ -2,7 +2,7 @@
 
 The general approach is described in [Creating Thread Specs](./CreatingThreadSpecs.md). We explain the math here. The following figure is of great help to understand what is going on. Black profile: theoretical parting line. The profiles we are going to create are red (internal thread) and blue (external thread). Note that the red and blue profiles are drawn assuming identical pitch diameters for both to clarify the figure. However, in reality external and internal threads do not have the same pitch diameter (see below).
 
-![Parting line of BSP-parallel thread with simplified external and internal thread profiles overlayed](imgs/BSPthread.jpg)
+![Parting line of BSP-parallel thread with simplified external and internal thread profiles overlaid](imgs/BSPthread.jpg)
 
 The relevant translation in done in the function calculateThreadlibSpecs() in BSPP_thread.awk.
 
@@ -11,7 +11,7 @@ Steps:
 - Pitch (P): Taken from table BSPP_thread.csv
 - Pitch diameter: external threads aim for a somewhat smaller pitch diameter (DPitchExt), internal threads for a larger one (DPitchInt). threadlib aims at the center of the acceptable range given in BSPP_thread.csv. For external thread, we have to choose between class A and class B. We decided for class A.
 - Major diameter (for external thread, think minor diameter for internal thread) is chosen in the center of the acceptable range given in BSPP_thread.csv => DMaxExt, DMinInt
-- Support diameter (DSupportExt, DSupportInt): Must be on the right side of the parting line. Otherwise no requirements from the norm. We choose the pitch diameter +/- 2 * 5/12 * H, where H is the full heigt of the fundamental triangle and +/- depends on external / internal thread. This is the middle between intended major / minor diameter and the corner of the fundamental triangle.
+- Support diameter (DSupportExt, DSupportInt): Must be on the right side of the parting line. Otherwise no requirements from the norm. We choose the pitch diameter +/- 2 * 5/12 * H, where H is the full height of the fundamental triangle and +/- depends on external / internal thread. This is the middle between intended major / minor diameter and the corner of the fundamental triangle.
 - The valleys of the actual part will be defined by the support (see above). The valleys of the profile are chosen to overlap somewhat with the support => DValleyExt, DValleyInt (these correspond to Rrot).
 
 

docs/CreatingThreadSpecs.md

@@ -1,20 +1,19 @@
 # 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.
+In the following, we explain how a thread spec (i.e., an entry in THREAD_TABLE.scad) is created. First, we will explain the basics of threads and how they are specified in the norms. Then, we will elaborate on how 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 black 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.
+As an example, we use British Standard Pipe parallel (BSPP) thread (see drawing below). The black curve shows the parting line between internal and external thread. In an ideal world, both threads are created according to the parting line. For BSP thread it is based on a fundamental triangle with a 55-degree angle rounded to a radius r.
 
 ![BSPP thread drawing](imgs/BSPthread.jpg)
 
      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.
+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 (which used to be [here](http://mdmetric.com/tech/thddat7.htm)): 
+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 (which used to be [here](http://mdmetric.com/tech/thddat7.htm)):
 
 <table>
  <tr>
@@ -108,28 +107,39 @@ Of course, it is not ok to introduce arbitrarily large allowances: The norm (BS
 
 ## Deriving threadlib Specs
 
-To simplify the thread profile, we want to avoid the rounding and replace it by a trapezoidal edge as shown in the image above in red and blue (internal and external thread, respectively).
+We want to approximate the thread profile by straight-line segments as shown in the sketch in red and blue (internal and external thread, respectively).
 
-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).
+It is clear that we have to match the pitch exactly.  Therefore, threadlib's 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
+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 thread profile 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)
+1) the allowed deviations given in the norm
+2) the rounding
 
-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.
+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 (see sketch at the top of this page).
 
 
 ## Adding Specs to threadlib
 
-To get the threads into threadlib, we currently do the following: 
+To get the threads into threadlib, we do the following: 
 
-- Add csv-file with original thread specs in design (e.g., "newthreads.csv")
-- Write an awk script (e.g., design/newthreads.awk) that translates this .csv file to tabular threadlib specs
-- Modify Makefile: Add a line like "cat design/newthreads.csv | awk -f design/newthreads.awk >> design/THREAD_TABLE.csv")
-- design/autogenerate.awk will translate the resulting THREAD_TABLE.csv into the final THREAD_TABLE.scad (same as the .csv but with added quoting and bracketing).
+- Tabulate specs as given in norm => design/newthreads.csv
+- Write design/newthreads.awk => translates design/newthreads.csv to tabular threadlib specs (see next step).
+- Add instructions to Makefile:
+  `cat design/newthreads.csv | awk -f design/newthreads.awk >> design/THREAD_TABLE.csv` Now, `make` will automatically run the script.
+- design/autogenerate.awk will translate the resulting THREAD_TABLE.csv into the final THREAD_TABLE.scad (same as the .csv but with added quoting and bracketing). This script is already there, you should not need to modify it.
 
-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 test' in the top-level directory or '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.
+The format of THREAD_TABLE.csv is:
 
+`DESIGNATOR, P, Rrot, Dsup, dr_0, z0, dr_1, z_1, dr_2, z_2, dr_3, z_3`
+
+The meaning of these values is explained in [Design of Threadlib](DesignOfThreadlib.md).
+
+
+## Adding Tests
+
+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 test` in the top-level directory or `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.
+
+For more information on testing, see [Unit Tests](UnitTests.md).

docs/DesignOfThreadlib.md

@@ -46,7 +46,7 @@ Why do we need P, Rrot, Dsup, *and* profile? Can we not include everything in pr
 
 *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 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 neighboring periods would exactly touch each other. This leads to rendering artifacts => P is stored separately 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

@@ -5,9 +5,11 @@ 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.
+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 MacOS's 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:
+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 is determined by looking at the thread designator. 
+
+Example:
 
 	/"[^,]+-ext/ {
 		# external threads have positive Rrot 
@@ -16,14 +18,14 @@ Every line of THREAD_TABLE.scad is fed to [tests/test_table.awk](../tests/test_t
 			print designator " FAIL: negative radius of rotation";
 			PASS = 0;
 		}
-		# test overlapp between thread and support
+		# test overlap 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).
+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:
 
@@ -48,10 +50,10 @@ Note that:
 
 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
+- 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.
+At the very end (`END {...}`), the awk script tests the value of PASS. If all tests were successful, 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.