From ae48012a6eb96f42a964d9fc6223087f7c7c1b3c Mon Sep 17 00:00:00 2001
From: Florian Stecker <mail@florianstecker.de>
Date: Tue, 17 Jan 2023 07:15:44 -0500
Subject: [PATCH] add documentation

---
 .gitignore   |  1 +
 README.md    | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 hyperbolic.c | 31 +++++++++++++++----------------
 3 files changed, 65 insertions(+), 16 deletions(-)
 create mode 100644 README.md

diff --git a/.gitignore b/.gitignore
index 1653d2c..12b1eb1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
 *.o
 hyperbolic
 output/
+README.html
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..07b9034
--- /dev/null
+++ b/README.md
@@ -0,0 +1,49 @@
+# hyperbolic tilings #
+
+A program to draw regular tilings of the hyperbolic plane by triangles as SVG files.
+
+## Setup ##
+
+GCC and GNU make are needed. To compile, just run `make`.
+
+## Usage ##
+
+The executable is called `hyperbolic` and is invoked as follows:
+
+    $ ./hyperbolic
+    Usage: ./hyperbolic <p> <q> <r> <n_elements> <word1> <word2> ...
+
+The arguments `p,q,r` specify the orders of the rotations `bc`, `ca` and `ab`, where `a,b,c` are the reflections along the three sides of the triangle. The parameter `n_elements` limits how many translates of the triangle are being drawn (1000 is a good default value, although for some values of `p,q,r` more are needed).
+
+The program can not only draw the tiling by triangles, but also the axes of specific hyperbolic elements in the triangle group or the fixed points of elliptic elements. To use this feature, just specify the group elements as additional arguments, written as words in the three reflections `a,b,c`. This will draw its axis/fixed point and that of all of its conjugates.
+
+## Examples ##
+
+    ./hyperbolic 5 5 5 5000 abc
+
+![(5,5,5) tiling with axes of abc and its conjugates](https://florianstecker.net/git_files/hyperbolic_tilings/tiling_555_abc.png)
+
+    ./hyperbolic 2 3 7 20000
+
+![(2,3,7) tiling](https://florianstecker.net/git_files/hyperbolic_tilings/tiling_237.png)
+
+    ./hyperbolic 2 3 7 20000 ab
+
+![(2,3,7) tiling](https://florianstecker.net/git_files/hyperbolic_tilings/tiling_237_ab.png)
+
+
+## Conversion to PDF or PNG ##
+
+If a different image format is required, the SVG files can easily be converted. Using [rsvg-convert] gives good results
+
+To convert to PNG (used for the images above):
+
+    rsvg-convert --format=png -w 600 -h 600 tiling_555_abc.svg -o tiling_555_abc.png
+
+To convert to PDF:
+
+    rsvg-convert --format=pdf -w tiling_555_abc.svg -o tiling_555_abc.pdf
+
+`maketiling.sh` is a convenience script which takes the same arguments as `hyperbolic`, but saves the SVG file in the folder `output/` (which has to be present) with a descriptive name and also converts it to PDF.
+
+[rsvg-convert]: https://gitlab.gnome.org/GNOME/librsvg
diff --git a/hyperbolic.c b/hyperbolic.c
index ce2b132..7775bc6 100644
--- a/hyperbolic.c
+++ b/hyperbolic.c
@@ -291,24 +291,23 @@ int main(int argc, const char *argv[])
 
 	nspecial_hyp = nspecial_rot = 0;
 	for(int i = 0; i < nspecial; i++) {
-		LOOP(j) {
-			int nreal;
+	    int j = 0;
+	    int nreal;
 
-			compute_word(ws, special[3*i+j], gen, argv[i+5], j, 0);
-			nreal = eigenvectors(special[3*i+j], special_eigenvectors[3*i+j], ws);
-			if(nreal == 3) {
-				special_attracting[nspecial_hyp] = column(special_eigenvectors[3*i+j], 0);
+	    compute_word(ws, special[3*i+j], gen, argv[i+5], j, 0);
+	    nreal = eigenvectors(special[3*i+j], special_eigenvectors[3*i+j], ws);
+	    if(nreal == 3) {
+		special_attracting[nspecial_hyp] = column(special_eigenvectors[3*i+j], 0);
 
-				// repelling = attracting of inverse
-				compute_word(ws, special[3*i+j], gen, argv[i+5], j, 1);
-				eigenvectors(special[3*i+j], special_eigenvectors[3*i+j], ws);
-				special_repelling[nspecial_hyp] = column(special_eigenvectors[3*i+j], 0);
-				nspecial_hyp++;
-			} else {
-				special_rotation[nspecial_rot] = column(special_eigenvectors[3*i+j], 0);
-				nspecial_rot++;
-			}
-		}
+		// repelling = attracting of inverse
+		compute_word(ws, special[3*i+j], gen, argv[i+5], j, 1);
+		eigenvectors(special[3*i+j], special_eigenvectors[3*i+j], ws);
+		special_repelling[nspecial_hyp] = column(special_eigenvectors[3*i+j], 0);
+		nspecial_hyp++;
+	    } else {
+		special_rotation[nspecial_rot] = column(special_eigenvectors[3*i+j], 0);
+		nspecial_rot++;
+	    }
 	}
 
 	fprintf(stderr, "%d special elements, %d rotations, %d hyperbolic\n", nspecial, nspecial_rot, nspecial_hyp);