From 4b03167544afbc9ec34aea5e7a20734ab5bc0b09 Mon Sep 17 00:00:00 2001
From: ian <ian>
Date: Sun, 25 Jan 2004 15:53:10 +0000
Subject: [PATCH] some docs

---
 layout/informat.txt | 52 +++++++++++++++++++++++++++++++++++++++++++++
 layout/layout       | 14 ++++++++----
 2 files changed, 62 insertions(+), 4 deletions(-)
 create mode 100644 layout/informat.txt

diff --git a/layout/informat.txt b/layout/informat.txt
new file mode 100644
index 0000000..3f0ad47
--- /dev/null
+++ b/layout/informat.txt
@@ -0,0 +1,52 @@
+Locations, angles, etc.
+
+ Key type is a `loc', which is a named location (absolute, 2D) and
+ direction (at the location).  Angles are generally positive
+ anticlockwise; bearings are angles measured from East.  The origin is
+ at the South-West.
+
+Syntaxes
+ New location
+  <identifier>
+ Existing location
+  [-]<identifier>  (- means reverse the sense)
+ Quantity (length/angle)
+  <number>[<unit>]
+  Angle units: d (degrees,default)  r (radians)
+  Length units: mm (default)  cm  m
+ Identifiers (of locs and objects) start with lc letter, then
+ alphanums and underscores
+
+Commands
+
+ abs P X Y A
+  Defines loc P given coordinates (distances) and absolute bearing
+
+ rel F T L R A
+  Defines loc T: start at loc F, go forward L, translate right R,
+  turn left A.
+
+ extend F T len L [R]        length L
+ extend F T upto U [R]       s.t. perpendicular at T passes through U
+ extend F T ang A R          subtending directionally A
+ extend F T uptoang A R      s.t. direction at T is A
+ extend F T parallel U R     s.t. direction at T is same as at U
+  Draws an arc or line from loc F, defining the other end as loc T.
+  If length R specified, draws an arc of radius R; R +ve curves to the
+  right; R -ve to the left.
+
+ defobj O
+ [commands]
+ enddef
+  Defines the object O.  Inside the definition, the commands do not
+  draw when the object is being defined.  The object has its own
+  coordinate space and its own location namespace.
+
+ obj[flip] O A F [P]
+  Places an instance of object O.  The loc defined inside O as F
+  (`formal parameter', F must be just <identifier>) is placed at
+  existing loc A (`actual parameter').  If prefix P (syntax is that of
+  an identifier) is specified, each other loc L inside O is exported
+  into the global namespace as a new loc PL.  If `flip' is used then
+  the object is placed with object-space y coordinates negated (ie, it
+  is mirrored so that the object's North exchanges with South).
diff --git a/layout/layout b/layout/layout
index c509ecc..5552581 100755
--- a/layout/layout
+++ b/layout/layout
@@ -372,7 +372,7 @@ sub arc ($$$$$$$) {
     my ($to, $endstatuses, $ctr,$from,$fromsense, $radius,$delta) = @_;
     # does parametric_segment to draw an arc centred on $ctr
     # from $from with radius $radius (this must be consistent!)
-    # and subtending an angle $delta.
+    # and directionally-subtending an angle $delta.
     # sets $to->... to be the other end, and returns $to
     # $fromsense is 1 or -1, and affects only the interpretation
     # of $from->{A} (not the result).
@@ -390,10 +390,14 @@ sub arc ($$$$$$$) {
 }
 
 sub cmd_join {
-    my ($from,$to,$how);
+    my ($from,$to,$how,$radius);
     $from= can(\&cva_idex);
     $to= can(\&cva_idex);
-    $how= can(cvam_enum(qw(arcs arcsm)));
+    $how= can(cvam_enum(qw(arcs arcsline arcline)));
+    if ($how eq 'arcsline') {
+	$radius= can(\&cva_len);
+    }
+    
     my ($sigma,$distfact, $theta,$phi, $a,$b,$c,$d2, $r,$cfrom);
     $sigma= v_bearing($from,$to);
     $distfact= v_dist($from,$to);
@@ -426,10 +430,12 @@ sub cmd_extend {
     $radius= cano(\&cva_len, 'Inf'); # +ve is right hand bend
     if ($radius eq 'Inf') {
 	print DEBUG "extend inf $len\n";
-	if ($how eq 'ang') { die "len of straight spec by angle"; }
 	if ($how eq 'upto') {
 	    $len= ($upto->{X} - $from->{X}) * cos($from->{A})
 		+ ($upto->{Y} - $from->{Y}) * sin($from->{A});
+	} elsif ($how eq 'len') {
+	} else {
+	    die "len of straight spec by angle";
 	}
 	printf DEBUG "len $len\n";
 	$to->{X}= $from->{X} + $len * cos($from->{A});
-- 
2.30.2