From f36f7048e6d95f4787d9dd8b75836df381826c3c Mon Sep 17 00:00:00 2001
From: Werner Almesberger <werner@openmoko.org>
Date: Tue, 14 Dec 2010 19:17:34 -0300
Subject: [PATCH] cameo: documented X/Y translation commands, some small
 improvements

- README: described the X/Y translation commands
- lang.y: print an error if the lower bound if larger than the upper bount
  in an "align" command
- lang.y: mention that "array" doesn't work as expected if in imperial mode
---
 cameo/README | 35 ++++++++++++++++++++++++++++++++++-
 cameo/lang.y |  6 ++++++
 2 files changed, 40 insertions(+), 1 deletion(-)

diff --git a/cameo/README b/cameo/README
index 73b41db..3116f37 100644
--- a/cameo/README
+++ b/cameo/README
@@ -40,6 +40,7 @@ Note that "clear" preserves the translation set with "align", "array",
 and "translate". This way, multiple files can be processed with the same
 translation.
 
+
 File output:
 
   write [<filename>]
@@ -47,6 +48,7 @@ File output:
 Writes all loaded paths in gnuplot format to the specified file. If the
 file name is omitted, "write" writes to standard output.
 
+
 Units:
 
   mm
@@ -68,13 +70,44 @@ Horizontal adjustments:
   align <ref> <x> <y>
   align <ref> <x0> <y0> <x1> <y1>
   array <x-step> <y-step> <x-index> <y-index>
-  translate <X> <y>
+  translate <x> <y>
   reset
 
+"translate" shifts the currently loaded paths by the specified distance.
+"align" is a more sophisticated form of "translate", which moves a
+reference point in the bounding box of the currently loaded paths either
+to a specified location (if used with three arguments) or to the
+respective point in a rectangle (if used with five arguments).
+
+The reference point is specified with a number as follows:
+
+7-----8-----9
+|           |
+4     5     6
+|           |
+1-----2-----3
+
+"1" is the lower left corner, "5" is the center, and so on.
+
+"array" is used when cutting several copies of the same piece. The first
+two arguments define the step between pieces while the second two
+arguments define how many steps in each direction are taken.
+
+"align" sets moves the toolpath to an absolute position while "array" and
+"translate" move relative to the current position. The total translation
+is remembered also across "clean", so that an alignment can be applied to
+multiple toolpaths.
+
+"reset" sets the translation to zero. The way "reset" is currently
+implemented, it does not affect the currently loaded toolpath. (But it's
+better to use it only with "clean".)
+
+
 Vertical adjustment:
 
   z [<z0>] <z0-pos>
   
+
 Tool compensation:
 
   tool [dog]
diff --git a/cameo/lang.y b/cameo/lang.y
index 0158c2e..d0a76f3 100644
--- a/cameo/lang.y
+++ b/cameo/lang.y
@@ -139,6 +139,11 @@ command:
 			int ref = $2;
 			double x, y;
 
+			if ($3 > $5)
+				yyerror("left edge > right edge");
+			if ($4 > $6)
+				yyerror("bottom > top");
+
 			ref_pick_xy(ref, $3, $4, $5, $6, &x, &y);
 			align(ref, x, y);
 		}
@@ -147,6 +152,7 @@ command:
 			double x = $2*$4;
 			double y = $3*$5;
 
+			/* @@@ known bug: doesn't work if not in metric mode */
 			translate(x, y, 0);
 		}
 	| TOK_CLEAR