FreeCalypso > hg > ueda-linux

comparison ueda/doc/uschemlang.txt @ 0:cd92449fdb51

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
initial import of ueda and ifctf-part-lib from ifctfvax CVS
author Space Falcon <falcon@ivan.Harhan.ORG>
date Mon, 20 Jul 2015 00:24:37 +0000
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:cd92449fdb51
1 uschem language for schematic sheets
2
3 uschem is the component of uEDA that deals with the graphical or non-graphical
4 schematic sheets as opposed to the MCL. These schematic sheets are ASCII text
5 files (conventional suffix is .usch, although it isn't hard-coded into any uEDA
6 tools) in a special language defined in this document.
7
8 At the high level each schematic sheet may be either graphical or non-graphical
9 and consists of a set of objects that embody electrical and/or graphical
10 information. Component objects (component instances) provide a link between the
11 schematic sheet and the MCL, Net and GraphNet objects declare electrical
12 interconnections (see netlisting.txt), GraphBlock objects serve as containers
13 for purely graphical elements, and a few other object types will be explained in
14 detail later. Most object types accept decorations, which are the uschem
15 syntactic term for information elements that are not objects in themselves, but
16 are attached to a particular object.
17
18 At the low level the uschem syntax is based on the same principle as C and many
19 other languages used in the UNIX world: the source file is treated as consisting
20 of tokens which are either self-delimiting or delimited by white space; with a
21 few exceptions all white space (spaces, tabs and newlines) is treated the same,
22 i.e., line boundaries have no special significance to the parser. The tokens
23 which make up the language consist of:
24
25 * ASCII characters (),;={} are self-delimiting tokens.
26
27 * A quoted string (enclosed in double quotes '"') is a quoted-string token.
28 To include a '"' character in a quoted string, escape it as '\"'; to include
29 a backslash '\', escape it as '\\'.
30
31 * The following tokens are delimited by white space, by any of the self-
32 delimiting tokens listed above, or by '%' comments (see below):
33
34 + Keywords
35 + Numbers (decimal integers)
36 + Any other strings (unquoted-string tokens)
37
38 Wherever the syntax calls for a string giving some user data, either a quoted or
39 an unquoted string may be given; quoted strings are required only if they
40 contain special characters. Keywords and numbers must not be quoted.
41
42 Comments
43
44 The uschem language supports two kinds of comments. The first kind are
45 PostScript-style comments. These comments are introduced by a '%' character and
46 continue to the end of the line (one of the few places in the uschem language
47 where newlines differ from other white space). This comment style is very
48 convenient, but they suffer from one serious problem: if a schematic sheet is
49 processed by a program that parses the original, does some transformations to
50 it, and writes out a new .usch file (uschem-rewrite(1) or the future graphical
51 schematic editor), PostScript-style comments will be lost because they are not
52 structured and thus cannot survive the parsing process.
53
54 The other kind of comments are structured comments. These take the form of
55 Comment objects or Comment decorations on other objects; the body of the comment
56 takes the form of a string token (usually quoted). Because they take their
57 proper place in the uschem language of objects and decorations, such structured
58 comments can survive processing by tools that manipulate schematic sheets at
59 that level.
60
61 Graphics model
62
63 The graphical aspects of uschem schematics have been borrowed heavily from
64 gschem, the schematic capture tool from the gEDA project - the latter is the
65 closest thing to a mainstream EDA package that has ever been used by the author
66 of uEDA. All geometric dimensions for graphical elements on schematic sheets as
67 well as the dimensions of the sheets themselves are given in gschem units, and
68 most of the commonly used graphics primitives have also been copied from gschem.
69 Users wanting to make use of the graphical features of uschem need to be
70 familiar with gschem as these gschem-derived graphical features won't be
71 described here in detail.
72
73 There is, however, one major difference between the graphics models of gschem
74 and uschem. gschem is a GUI application and its graphics primitives are
75 intended primarily for on-screen display and editing; gschem supports PostScript
76 output as an afterthought. uschem on the other hand is designed with the
77 philosophy that PostScript is the canonical and authoritative representation of
78 a graphical schematic sheet; whatever form is used to represent graphical
79 elements in the source code, the assumption is that they are all ultimately
80 destined to become PostScript.
81
82 Graphical elements emitted into the PostScript output by uschem-print(1) come
83 from the following sources:
84
85 * GraphBlock structures (objects or decorations) which are containers for purely
86 graphical elements in schematic sheets;
87
88 * Graphical symbols pulled from the library to represent component instances as
89 well as for other purposes - see graphsyms.txt;
90
91 * Text emitted by DisplayAttr and DisplayNetName decorations;
92
93 * Lines drawn for GraphNet, NetLine and BusSeg objects.
94
95 GraphBlock structures may be of two forms: GraphBlockG and GraphBlockPS. The
96 former contain gschem code, the latter contain PostScript code. PostScript is
97 the native form; gschem code is printed by turning it into PostScript, hence
98 GraphBlockPS can do everything that GraphBlockG can plus much more. GraphBlockG
99 should be considered a backward compatibility feature. A similar situation
100 exists with graphical symbols as described more fully in graphsyms.txt.
101
102 See psfeatures.txt for the information you need to know in order to write
103 PostScript code for inclusion into GraphBlockPS structures or symbols.
104
105 Coordinate system
106
107 As already noted earlier, all graphical coordinates are given in gschem units.
108 Analogously to both gschem and PostScript default the origin of the coordinate
109 system is in the lower left corner; x coordinates increase to the right and y
110 coordinates increase upward. There is, however, one subtle difference between
111 gschem and uschem coordinate systems. In gschem schematic sheets the absolute
112 coordinates are essentially arbitrary and one needs to use a special titleblock
113 "component" to set the overall dimensions of the drawing sheet; the coordinates
114 that really matter then need to be calculated relative to the arbitrary ones of
115 that titleblock component. uschem has done away with such silliness and every
116 graphical schematic sheet in the uschem language begins with an explicit size
117 declaration.
118
119 The sheet size declaration given at the beginning of a uschem sheet sets the
120 effective limits for the coordinate system, but it does not cause any border or
121 title block to be drawn. If such features are desired (they normally are), they
122 need to be embodied in a GraphBlock object.
123
124 One gschem misfeature that has unfortunately been retained in uschem is the
125 fictitious nature of the drawing sizes. Using gschem and following the size
126 conventions set for its standard symbol library, one has to declare the drawing
127 as having size D (use title-D.sym) in order to make it reasonable for printing
128 in size B; this situation unfortunately remains in uschem. The sheet size
129 declaration merely establishes the size of the in-sheet coordinate system in the
130 fake gschem units, whereas the actual print size is given on the command line to
131 uschem-print(1). uschem's PostScript prolog code calculates and effects the
132 necessary scaling.