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.