Add a README file.

diff --git a/Makefile.am b/Makefile.am
index e2c3fc3fbd7c2389069136c52036ff44b9e1ea1a..9cda5060192f50a5378e536e9c07c6f5ef869df4 100644 (file)
--- a/Makefile.am
+++ b/Makefile.am
@@ -11,7 +11,7 @@ DISTCLEANFILES =
 MOSTLYCLEANFILES =
 MAINTAINERCLEANFILES =
 EXTRA_LIBRARIES =
-EXTRA_DIST = INSTALL
+EXTRA_DIST = INSTALL README.md
 
 AM_CPPFLAGS = -I$(top_builddir)/lib -I$(top_srcdir)/lib \
               -DLOCALEDIR=\"$(localedir)\"

diff --git a/README.md b/README.md
new file mode 100644 (file)
index 0000000..5abf599
--- /dev/null
+++ b/README.md
@@ -0,0 +1,68 @@
+Slotifier is a simple program which takes an Excellon drill file input,
+searches for overlapping drill hits, and generates a new drill file with
+those hits converted to a single slot (G85 entry in the drill file).
+
+This is useful when using a PCB tool which does not generate such slots
+directly, but you require this format for fabrication.  Simply use overlapping
+drill hits in the PCB tool to represent slots, then run slotifier on the drill
+file before sending to the fab.
+
+The types of slots that can be produced with this tool are limited: they must
+be straight lines and must have the same thickness throughout.  Slotifier uses
+a simple heuristic to convert holes to slots, and might behave unexpectedly if
+drill hits overlap in complex ways, see below.
+
+# Prerequisites
+
+Slotifier is written in C, so a working C compiler is required.
+
+The [libgerbv library][gerbv-homepage] is used to process the Excellon drill
+file format.  It must be a sufficiently recent version with support for G85
+slots: the first version to support such slots is included with gerbv 2.7.
+
+Furthermore, slotifier requires the [CNearTree library][neartree-homepage]
+in order to compute the overlap relation between holes.
+
+Optionally, in order to support localized program messages the [GNU libintl
+library][gettext-homepage] (included with the GNU C library) is required.
+
+[gerbv-homepage]: http://gerbv.geda-project.org/
+[neartree-homepage]: http://neartree.sourceforge.net/
+[gettext-homepage]: https://www.gnu.org/software/gettext/
+
+# Theory of operation
+
+Slotifier works by locating groups of drill hits which are considered
+mergeable.  Two holes are considered to _overlap_ if and only if the centre of
+either hole is positioned within the other hole, and the transitive closure of
+this overlap relation gives the _mergeable_ relation.  Thus, holes A and B
+are mergeable if there is some sequence of overlapping holes, starting from
+A, which leads to B.
+
+The mergeable property is an equivalence relation on the holes, so the holes
+can be partitioned into equivalence classes.  Every such class with more than
+one hole in it is then converted into a slot as follows:
+
+* Two holes are chosen from the class such that the straight-line distance
+  between their centres is maximized.  These two centres are used as the
+  endpoints of the slot.
+
+* The tool with the greatest diameter from all the holes in the class is used
+  as the tool for the slot.
+
+In either case, it is unspecified which option is chosen when there is more
+than one maximum.
+
+For best results, the designer should ensure that mergeable holes form an
+approximate straight line and use the same tools.
+
+# License
+
+Slotifier is free software: you can redistribute it and/or modify it under
+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.
+
+{::comment}
+Copyright © 2019, 2021 Nick Bowler
+{:/comment}