r5344 - developers/werner/fped

[werner at docs.openmoko.org]

Author: werner
Date: 2009-07-31 02:07:41 +0200 (Fri, 31 Jul 2009)
New Revision: 5344

Added:
   developers/werner/fped/README
Modified:
   developers/werner/fped/TODO
   developers/werner/fped/error.c
Log:
Added README.



Added: developers/werner/fped/README
===================================================================
--- developers/werner/fped/README	                        (rev 0)
+++ developers/werner/fped/README	2009-07-31 00:07:41 UTC (rev 5344)
@@ -0,0 +1,273 @@
+fped - Footprint editor
+=======================
+
+fped is an editor that allows the interactive creation of footprints of
+electronic components. Footprint definitions are stored in a text format
+that resembles a programming language.
+
+The language is constrained such that anything that can be expressed in
+the textual definition also has a straightforward equivalent operation
+that can be performed through the GUI.
+
+
+Geometry model
+==============
+
+The geometry model consists of frames, vectors, and objects. The shape of
+objects is defined by a number of points. These points are produced by
+concatenating vectors.
+
+E.g., to draw a line from (1mm, 1mm) to (2mm, 2mm), one would make a
+vector from the origin to (1mm, 1mm) and one either from the origin or
+from the previous vector to (2mm, 2mm), and then make a line connecting
+the two points.
+
+
+Units
+-----
+
+fped can calculate in mm and mil. Units are specified by following a
+number with "mm" or "mil", separated by zero or more spaces or tabs.
+
+Examples:
+
+1mm
+2 mil
+
+Units can be mixed in calculations, e.g.,
+
+a = 1mm+20mil
+b = 10*1mm
+
+All values used as dimensions must be either mm or mil.
+
+
+Vectors
+-------
+
+Vectors can be anonymous or they can be named for future reference:
+
+.vec <base> <x-expr>, <y-expr>
+<identifier> = .vec <base> <x-expr>, <y-expr>
+
+The base can be one of the following items:
+
+- @: the origin of the frame containing the vector
+- .: the end of the previous vector in this frame
+- <identifier>: the name of a previous vector in the same frame
+
+The following example would draw the line described in the previous
+section:
+
+a = .vec @ 1mm, 1mm
+b = .vec . 1mm, 1mm
+.line a b
+
+
+Silk screen objects
+-------------------
+
+The output of fped is a footprint definition that contains pads and silk
+screen drawings (we may add more layers in the future). These items are
+called "objects". Their geometry is defined through points obtained with
+vectors.
+
+A line connects two points:
+
+.line <point-a> <point-b>
+
+The points can be specified with @, ., and an identifier, just like
+a vector base.
+
+A rectangle has sides parallel to the x and y axis and is defined
+by two diagonally opposite corners:
+
+.rect <point-a> <point-b>
+
+A circle is defined by its center and a point on the circle:
+
+.arc <center> <point>
+
+This example draws a unit circle:
+
+.vec @ 1mm, 0mm
+.arc @ .
+
+An arc is like a circle, but the part of the circle drawn is determined
+by two points. The first point determines the radius and the starting
+angle. The second point only determines the end angle but its distance
+from the center is ignored.
+
+.arc <center> <radius>, <end>
+
+Note the comma between the radius and the end angle. The arc is drawn
+in a counter-clockwise direction. The following example draws an arc
+of the unit circle in the x > 0, y > 0 quadrant:
+
+from = .vec @ 1mm, 0mm
+to = .vec @ 0mm, 1mm
+.arc @ from, to
+
+
+Pads
+----
+
+Pads are similar to rectangles, but they also have a name.
+
+.pad "<name>" <point-a> <point-b>
+
+Variables can be expanded in a pad's name by prefixing their name with
+a dollar sign. The ${name} syntax is also available.
+
+Example:
+
+.vec @ 1mm, 1mm
+.pad "1" @ .
+
+
+Frames
+------
+
+Frames are used to group things and to reuse them multiple times. Frames
+must be defined before they can be used:
+
+.frame <name> {
+    ... items ...
+}
+
+Once defined, a frame is placed at a given location with
+
+.frame <name> <point>
+
+The frame definitions must precede all other items in a footprint
+description. Frames cannot be defined inside other frames, but frames
+can invoke each other recursively.
+
+For example, this puts two unity squares, one centered at (0 mm, 0 mm),
+the other at (2 mm, 0 mm):
+
+.frame unit_square {
+	a = .vec @ -0.5mm, -0.5mm
+	b = .vec . 1mm, 1mm
+	.rect a b
+}
+
+.frame unit_square @
+.vec @ 2mm, 0mm
+.frame unit_square .
+
+
+Names and variables
+===================
+
+fped uses several name spaces:
+
+- frame names occupy one global name space
+
+- vector names occupy name spaces delimited by the frame they're
+  contained in. A vector name is only visible inside the frame in which
+  it is defined.
+  
+- variable names occupy name spaces delimited by the frame they're
+  contained in. A variable lookup starts in the frame in which the
+  corresponding expression appears and propagates to outer frames
+  until the variable is found.
+
+- pads occupy one global name space (this is currently not enforced)
+
+Note that names cannot be redefined. E.g., this does not work:
+
+a = 1
+a = a+1
+
+The names spaces of frames, vectors, variables, and pads are separate
+from each other.
+
+
+Simple variables
+----------------
+
+A variable with a single value is defined with the usual C-like
+assignment syntax:
+
+<identifier> = <expression>
+
+Example:
+
+a = b+2
+
+
+Loops
+-----
+
+A loop is a variable with a range of values:
+
+<identifier> = <from>, <to>
+
+The variable assumes all the values i for <from> <= i <= <to>, in
+increments of one. E.g.,
+
+n = 1, 3
+
+and
+
+n = 1, 3
+
+both assigns the values 1, 2, and 3 to the variable "n".
+
+When a loop is executed, the objects contained in the body of the
+enclosing frame are generated for each value of the variable. If
+a frame contains multiple loops, all possible combinations of the
+values are generated.
+
+The following example draws three concentric circles around the
+origin, with radii 1, 2, and 3:
+
+x = 1, 3
+.vec @ x*1mm, 0mm
+.arc @ .
+
+
+Tables
+------
+
+Tables combine values for multiple variables. Like loops, they are
+used to iteratively generate objects. A table begins with a row of
+variable names, followed by one or more rows with values. Rows are
+enclosed in curly braces and their elements are separated by commas.
+
+.table
+    { <identifier>, ... }
+    { <expression>, ... }
+    ...
+
+Like loops, tables are iterated to generate objects. The following
+example is equivalent to the one in the previous section:
+
+.table
+    { x }
+    { 1mm }
+    { 2mm }
+    { 3mm }
+.vec @ x, 0mm
+.arc @ .
+
+Note that we can set the unit of the values directly in this case.
+
+Iteration is performed over rows. All variables of the table are set
+to the value in the respective row at the same time. For example, in
+
+.table
+    { x, y }
+    { 1, 2 }
+    { 3, 4 }
+
+(x, y) assume the values (1, 2) and (3, 4).
+
+
+Expressions
+===========
+
+Expressions can contain numeric constants (in non-exponential notation),
+variable names, the arithmetic operations +, -, *, /, and unary -.
+Parentheses can be used to change precedence.

Modified: developers/werner/fped/TODO
===================================================================
--- developers/werner/fped/TODO	2009-07-30 21:18:07 UTC (rev 5343)
+++ developers/werner/fped/TODO	2009-07-31 00:07:41 UTC (rev 5344)
@@ -1,5 +1,4 @@
 - make frame selection work
-- add table/var/loop representation
 - Q: should loop be (start, last) or (start, iterations) ?
 - add row selection
 - change vector circle color ? (also, highlight on hover ?)
@@ -19,7 +18,7 @@
 - syntax seems a little cryptic. too many dots and at signs.
 - add measurements
 - arc syntax is weird, with comma where we use spaces
-- Q: allow reassignment of vector names ?
+- Q: allow reassignment of vector names ? (no: would cause confusion in GUI)
 - add KiCad output
 - add postscript output
 - add option to include/omit helper vecs and frames (display and postscript)
@@ -28,3 +27,6 @@
 - Q: add frame arguments ? (e.g., .frame pad(pin_num_offset) ...)
 - Q: should we make it a requirement to generate objects only once ?
 - convert status display to table
+- advanced: non-standard solder mask
+- advanced: solder paste exceptions (subtractive, additive)
+- advanced: silk line width

Modified: developers/werner/fped/error.c
===================================================================
--- developers/werner/fped/error.c	2009-07-30 21:18:07 UTC (rev 5343)
+++ developers/werner/fped/error.c	2009-07-31 00:07:41 UTC (rev 5344)
@@ -31,7 +31,7 @@
 	va_start(ap, fmt);
 	vfprintf(stderr, fmt, ap);
 	va_end(ap);
-	fprintf(stderr, "near \"%s\"\n", yytext);
+	fprintf(stderr, " near \"%s\"\n", yytext);
 	exit(1);
 }