--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/ueda/doc/uschemlang.txt	Mon Jul 20 00:24:37 2015 +0000
@@ -0,0 +1,132 @@
+uschem language for schematic sheets
+
+uschem is the component of uEDA that deals with the graphical or non-graphical
+schematic sheets as opposed to the MCL.  These schematic sheets are ASCII text
+files (conventional suffix is .usch, although it isn't hard-coded into any uEDA
+tools) in a special language defined in this document.
+
+At the high level each schematic sheet may be either graphical or non-graphical
+and consists of a set of objects that embody electrical and/or graphical
+information.  Component objects (component instances) provide a link between the
+schematic sheet and the MCL, Net and GraphNet objects declare electrical
+interconnections (see netlisting.txt), GraphBlock objects serve as containers
+for purely graphical elements, and a few other object types will be explained in
+detail later.  Most object types accept decorations, which are the uschem
+syntactic term for information elements that are not objects in themselves, but
+are attached to a particular object.
+
+At the low level the uschem syntax is based on the same principle as C and many
+other languages used in the UNIX world: the source file is treated as consisting
+of tokens which are either self-delimiting or delimited by white space; with a
+few exceptions all white space (spaces, tabs and newlines) is treated the same,
+i.e., line boundaries have no special significance to the parser.  The tokens
+which make up the language consist of:
+
+* ASCII characters (),;={} are self-delimiting tokens.
+
+* A quoted string (enclosed in double quotes '"') is a quoted-string token.
+  To include a '"' character in a quoted string, escape it as '\"'; to include
+  a backslash '\', escape it as '\\'.
+
+* The following tokens are delimited by white space, by any of the self-
+  delimiting tokens listed above, or by '%' comments (see below):
+
+  + Keywords
+  + Numbers (decimal integers)
+  + Any other strings (unquoted-string tokens)
+
+Wherever the syntax calls for a string giving some user data, either a quoted or
+an unquoted string may be given; quoted strings are required only if they
+contain special characters.  Keywords and numbers must not be quoted.
+
+Comments
+
+The uschem language supports two kinds of comments.  The first kind are
+PostScript-style comments.  These comments are introduced by a '%' character and
+continue to the end of the line (one of the few places in the uschem language
+where newlines differ from other white space).  This comment style is very
+convenient, but they suffer from one serious problem: if a schematic sheet is
+processed by a program that parses the original, does some transformations to
+it, and writes out a new .usch file (uschem-rewrite(1) or the future graphical
+schematic editor), PostScript-style comments will be lost because they are not
+structured and thus cannot survive the parsing process.
+
+The other kind of comments are structured comments.  These take the form of
+Comment objects or Comment decorations on other objects; the body of the comment
+takes the form of a string token (usually quoted).  Because they take their
+proper place in the uschem language of objects and decorations, such structured
+comments can survive processing by tools that manipulate schematic sheets at
+that level.
+
+Graphics model
+
+The graphical aspects of uschem schematics have been borrowed heavily from
+gschem, the schematic capture tool from the gEDA project - the latter is the
+closest thing to a mainstream EDA package that has ever been used by the author
+of uEDA.  All geometric dimensions for graphical elements on schematic sheets as
+well as the dimensions of the sheets themselves are given in gschem units, and
+most of the commonly used graphics primitives have also been copied from gschem.
+Users wanting to make use of the graphical features of uschem need to be
+familiar with gschem as these gschem-derived graphical features won't be
+described here in detail.
+
+There is, however, one major difference between the graphics models of gschem
+and uschem.  gschem is a GUI application and its graphics primitives are
+intended primarily for on-screen display and editing; gschem supports PostScript
+output as an afterthought.  uschem on the other hand is designed with the
+philosophy that PostScript is the canonical and authoritative representation of
+a graphical schematic sheet; whatever form is used to represent graphical
+elements in the source code, the assumption is that they are all ultimately
+destined to become PostScript.
+
+Graphical elements emitted into the PostScript output by uschem-print(1) come
+from the following sources:
+
+* GraphBlock structures (objects or decorations) which are containers for purely
+  graphical elements in schematic sheets;
+
+* Graphical symbols pulled from the library to represent component instances as
+  well as for other purposes - see graphsyms.txt;
+
+* Text emitted by DisplayAttr and DisplayNetName decorations;
+
+* Lines drawn for GraphNet, NetLine and BusSeg objects.
+
+GraphBlock structures may be of two forms: GraphBlockG and GraphBlockPS.  The
+former contain gschem code, the latter contain PostScript code.  PostScript is
+the native form; gschem code is printed by turning it into PostScript, hence
+GraphBlockPS can do everything that GraphBlockG can plus much more.  GraphBlockG
+should be considered a backward compatibility feature.  A similar situation
+exists with graphical symbols as described more fully in graphsyms.txt.
+
+See psfeatures.txt for the information you need to know in order to write
+PostScript code for inclusion into GraphBlockPS structures or symbols.
+
+Coordinate system
+
+As already noted earlier, all graphical coordinates are given in gschem units.
+Analogously to both gschem and PostScript default the origin of the coordinate
+system is in the lower left corner; x coordinates increase to the right and y
+coordinates increase upward.  There is, however, one subtle difference between
+gschem and uschem coordinate systems.  In gschem schematic sheets the absolute
+coordinates are essentially arbitrary and one needs to use a special titleblock
+"component" to set the overall dimensions of the drawing sheet; the coordinates
+that really matter then need to be calculated relative to the arbitrary ones of
+that titleblock component.  uschem has done away with such silliness and every
+graphical schematic sheet in the uschem language begins with an explicit size
+declaration.
+
+The sheet size declaration given at the beginning of a uschem sheet sets the
+effective limits for the coordinate system, but it does not cause any border or
+title block to be drawn.  If such features are desired (they normally are), they
+need to be embodied in a GraphBlock object.
+
+One gschem misfeature that has unfortunately been retained in uschem is the
+fictitious nature of the drawing sizes.  Using gschem and following the size
+conventions set for its standard symbol library, one has to declare the drawing
+as having size D (use title-D.sym) in order to make it reasonable for printing
+in size B; this situation unfortunately remains in uschem.  The sheet size
+declaration merely establishes the size of the in-sheet coordinate system in the
+fake gschem units, whereas the actual print size is given on the command line to
+uschem-print(1).  uschem's PostScript prolog code calculates and effects the
+necessary scaling.