Fix docs (#44)

Docs

* Fixed broken links (to mdmetrics.com) in docs/* and README.rst
* Removed externally rendered formula (broken link) in BSPPthread.md
* Added explanation for tap module to README.rst
  which also required a new image and a line in the docs/Makefile

CONTRIBUTING

* Added CONTRIBUTING (closes #3)

CONTRIBUTING.md

@@ -0,0 +1,65 @@
+# How to contribute to threadlib
+
+Thank for considering a contribution to threadlib! Any help is greatly
+appreciated.
+
+
+## Did you find an issue?
+
+* Check whether your issue has already been reported by searching under
+  [existing issues](https://github.com/adrianschlatter/threadlib/issues).
+
+* If don't find an issue addressing the problem, open a new issue.
+
+* Choose a meaningful title, describe clearly what you consider to be a
+  problem.
+
+* If possible, provide example code or other means to make it easy for a
+  maintainer to reproduce your problem.
+
+
+## Did you write a patch?
+
+You already have a solution for an issue or a new feature? All the better! A
+pull request ("PR") is what you want to do.
+
+* Open a new [pull-request](https://github.com/adrianschlatter/threadlib/pulls)
+  with your patch.
+
+* Try to create PRs that address a specific issue/feature/topic.
+
+* Avoid PRs containing an assortment of unrelated fixes and features. Better
+  split it into separate PRs for each topic.
+
+* Clean up your code before creating a pull request: Remove code that you have
+  commented out for debugging, remove test code you have added, e.g., inside
+  threadlib.scad.
+
+* Make sure the PR's description clearly describes the problem and your solution.
+  Include relevant issue numbers if appropriate.
+
+* You increase the chances of quick acceptance of your PR significantly if you
+  have taken measures to assure quality (such as writing and passing tests).
+
+
+## You intend to contribute new threads?
+
+That's what we need the most! This is how to do it:
+
+* Find the specs (usually specified in a norm, sometimes published openly)
+
+* Convert these specs for use in threadlib:
+
+  * Find help on this topic in [Design of threadlib](docs/DesignOfThreadlib.md)
+    and [Creating Thread Specs](docs/CreatingThreadSpecs.md)
+
+  * Use existing threads as examples. You find them beneath design/
+
+* When done, proceed with a pull request (see "Did you write a patch?" above)
+  
+
+## Final remarks
+
+Currently, threadlib is maintained in the spare time of a single person having
+a family and a job. If you do not get immediate feedback to your issue or pull
+request, please have some patience.

README.rst

@@ -98,6 +98,32 @@ argument for higbee_arc):
 Note that for a nut you also have to specify an outer diameter. The inner
 diameter is implicitly given by the thread designator ("M12x0.5" in this case).
 
+To make a threaded hole (e.g. in a plate), an intuitive approach would be to
+create the difference of the plate and a bolt. However, this part would not work
+well in practice: You need a little space around the bolt to avoid collisions.
+threadlib's solution is to provide the tap module:
+
+.. code-block:: OpenSCAD
+
+        tap("G1/2", turns=5);
+
+.. image:: docs/imgs/tap-G1o2.png
+        :alt: G1/2 tap
+
+The tap shown above *is* intended for use like this and has accounted for the
+allowances needed in practice. Also, it will create the tapers:
+
+.. code-block:: OpenSCAD
+
+   difference() {
+        part_to_be_tapped_here();
+        tap("G1/2", turns=5);
+   }
+
+Make sure that the tap extends a tiny bit out of the part to be tapped.
+Otherwise, you will end up with infinitely thin artifacts covering the entrance
+of your tapped hole.
+
 If you only need the threads alone:
 
 .. code-block:: OpenSCAD
@@ -107,8 +133,9 @@ If you only need the threads alone:
 .. image:: docs/imgs/thread-G1o2-ext.png
         :alt: G1/2 external thread
  
-Then, add the support you want. In the simplest case, a cylinder (which is what
+(Note: You need to specify whether you want internal ("-int") or external
-nut(...) uses):
+("-ext") thread here.) Then, add the support you want. In the simplest
+case, a cylinder (which is what nut(...) uses):
 
 .. code-block:: OpenSCAD
 
@@ -131,11 +158,15 @@ List of supported threads
 
 Currently, threadlib knows these threads:
 
-- `Metric threads <http://mdmetric.com/tech/M-thead%20600.htm>`__ (coarse, fine, and super-fine pitches) M0.25 to M600
+- Metric threads (coarse, fine, and super-fine pitches) M0.25 to M600.
 - Unified Inch Screw Threads (UNC, UNF, UNEF, 4-UN, 6-UN, 8-UN, 12-UN,
   16-UN, 20-UN, 28-UN, and 32-UN). All threads are class 2 threads.
-- `BSP parallel thread <https://www.amesweb.info/Screws/British-Standard-Pipe-Parallel-Thread-BSPP.aspx>`__ G1/16 to G6
+- `BSP parallel thread
-- `PCO-1881 <https://www.bevtech.org/assets/Committees/Packaging-Technology/20/3784253-20.pdf>`__ (PET-bottle thread)
+  <https://www.amesweb.info/Screws/British-Standard-Pipe-Parallel-Thread-BSPP.aspx>`__
+  G1/16 to G6. All threads are class A threads.
+- `PCO-1881
+  <https://www.bevtech.org/assets/Committees/Packaging-Technology/20/3784253-20.pdf>`__
+  (PET-bottle thread)
 
 
 Extensibility
@@ -166,6 +197,6 @@ Change Log
 - 0.3: Unified Inch Screw Threads (UNC, UNF, UNEF, 4-UN, 6-UN, 8-UN, 12-UN,
   16-UN, 20-UN, 28-UN, and 32-UN. Fixed problem with PCO-1881-int. Fixed problem
   with G-ext threads . New build system. 
-- 0.2: `Metric threads <http://mdmetric.com/tech/M-thead%20600.htm>`__, `PCO-1881 <https://www.bevtech.org/assets/Committees/Packaging-Technology/20/3784253-20.pdf>`__
+- 0.2: Metric threads, `PCO-1881 <https://www.bevtech.org/assets/Committees/Packaging-Technology/20/3784253-20.pdf>`__
 - 0.1: Initial release supporting `BSP parallel thread <https://www.amesweb.info/Screws/British-Standard-Pipe-Parallel-Thread-BSPP.aspx>`__
 

docs/BSPPthread.md

@@ -15,9 +15,7 @@ Steps:
 - 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).
 
 
-However, this is not yet what we need. As we do not want the rounding in the profile, we have to adjust the "crest" diameters of the straightened profile accordingly. Again, the criterion is to define create a profile that strictly remains on its own side of the parting line.
+However, this is not yet what we need. As we do not want the rounding in the profile, we have to adjust the "crest" diameters of the straightened profile accordingly. Again, the criterion is to create a profile that strictly remains on its own side of the parting line.
-
-![Formula to calculate r_crest](https://quicklatex.com/cache3/38/ql_000121f710d4df1820cd5937b27b7838_l3.png)
 
 ![The 4 points of the thread profile in OpenSCADs x-y plane](imgs/ThreadProfile.png)
 

docs/CreatingThreadSpecs.md

@@ -6,15 +6,15 @@ In the following, we explain how a thread spec (i.e., an entry in THREAD_TABLE)
 ## 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.
+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.
 
-![BSPP thread drawing](http://mdmetric.com/tech/55deg228.gif) 
+![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.
 
-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): 
+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,10 +108,8 @@ 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 here (red: internal, blue external thread): 
+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).
 
-![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. 

docs/Makefile

@@ -1,6 +1,6 @@
 os = /usr/local/bin/openscad
 opts =
-imgs = bolt-M4.png nut-M12x0.5.png nutNbolt.png thread-G1o2-ext.png thread-G1o2-ext-10turns.png flexible.png
+imgs = bolt-M4.png nut-M12x0.5.png nutNbolt.png thread-G1o2-ext.png thread-G1o2-ext-10turns.png flexible.png tap.png
 
 .PHONY: all
 all: $(imgs)
@@ -21,7 +21,11 @@ thread-G1o2-ext.png: thread.scad
 	$(os) $(opts) --D 'type="G1/2-ext"' --D 'turns=5' --D 'higbee_arc=20' --camera=-0.7,-0.6,3.4,75,0,110,57 --imgsize=2048,2048 --projection=ortho -o $@ $<
 
 flexible.png: flexible.scad
-	$(os) $(opts) --D 'type="G1/2-ext"' --D 'turns=5' --D 'higbee_arc=20' --camera=-0.7,-0.6,3.4,75,0,110,57 --imgsize=2048,2048 --projection=ortho -o $@ $<$
+	$(os) $(opts) --D 'type="G1/2-ext"' --D 'turns=5' --D 'higbee_arc=20' --camera=-0.7,-0.6,3.4,75,0,110,57 --imgsize=2048,2048 --projection=ortho -o $@ $<
+
+tap.png: tap.scad
+	$(os) $(opts) --D 'type="G1/2"' --D 'turns=5' --D 'higbee_arc=20' --camera=7,15.3,3.45,87,0,333,65 --imgsize=2048,2048 --projection=ortho -o $@ $<
+
 
 .PHONY: clean
 clean:

docs/MetricThread.md

@@ -1,6 +1,6 @@
 # Metric Thread
 
-![Metric thread specs](http://mdmetric.com/tech/din13pix.jpg)
+![Metric thread specs](https://upload.wikimedia.org/wikipedia/commons/thumb/4/4b/ISO_and_UTS_Thread_Dimensions.svg/2560px-ISO_and_UTS_Thread_Dimensions.svg.png)
 
 metric_thread.csv provides the numbers given in the norm (no thinking done there, just copying). metric_thread.awk - as usual - calculates the threadlib specs. 
 

docs/tap.scad

@@ -0,0 +1,3 @@
+use <threadlib/threadlib.scad>;
+
+tap("G1/2", 5);