layout/informat.txt

   1 Locations, angles, etc.
   2
   3  Key type is a `loc', which is a named location (absolute, 2D) and
   4  direction (at the location).  Angles are generally positive
   5  anticlockwise; bearings are angles measured from East.  The origin is
   6  at the South-West.
   7
   8 Syntaxes
   9  New location
  10   <identifier>
  11   -<identifier>       reverse the sense (ie, 180 degrees off)
  12  Existing location
  13   <identifier>        simply the named location
  14   -<identifier>       reverse the sense (ie, 180 degrees off)
  15   O![-]<identifier>   the location from the specified object
  16                       in whatever coordinate system that object
  17                       happens to have
  18   ^O![-]<identifier>  the same, but the object is flipped
  19                       N-S first (see `part' and `objflip')
  20  Quantity (length/angle)
  21   <number>[<unit>]
  22   Angle units: d (degrees,default)  r (radians)
  23   Length units: mm (default)  cm  m
  24  Identifiers (of locs and objects) start with lc letter, then
  25  alphanums and underscores
  26
  27 Commands
  28
  29  abs P X Y A
  30   Defines loc P given coordinates (distances) and absolute bearing
  31
  32  rel F T [L R A]
  33   Defines loc T: start at loc F, go forward L, translate right R,
  34   turn left A (defaults are all 0).
  35
  36  layer K[L]
  37   K is layer kind (letters and `_', may be empty), L is a layer depth
  38   (digits, or `=' meaning current layer, or `*' meaning output layer;
  39   default for L is `='; default KL at start of file is `layer 5').
  40   Controls drawing style, by selecting appropriate parts of the track
  41   and locs to draw, according to element selection rules.  Default
  42   outcomes:
  43     K         result (description)     result (element letters)
  44     empty     default track            RLMNasco
  45     `s'       nothing (`silent')       -
  46     `l'       centrelines only         CLMNarso
  47     other     everything               ARSCLMNO
  48
  49  extend F T len L [R]        length L
  50  extend F T upto U [R]       s.t. perpendicular at T passes through U
  51  extend F T ang A R          subtending directionally A
  52  extend F T uptoang A R      s.t. direction at T is A
  53  extend F T parallel U R     s.t. direction at T is same as at U
  54   Draws an arc or line from loc F, defining the other end as loc T.
  55   If length R specified, draws an arc of radius R; R +ve curves to the
  56   right; R -ve to the left.
  57
  58  join F T R [S ...]
  59   Joins one existing loc, F, to another, T.  F's direction points to
  60   the new track; T's away - ie the added track leaves F in F's
  61   direction and arrives at T in T's direction.  R is the minimum curve
  62   radius allowed.  S selects from the available solutions, and may be
  63   any of the following
  64      long                  prefer longer length solution
  65      short                 prefer shorter length solution
  66      right|left            prefer mostly bending to the left resp. right
  67      beginright|beginleft  prefer first bend to the right
  68      endright|endleft      prefer final bend to the right
  69      [!]twoarcs            prefer [not] two circular arcs of equal radius
  70      [!]arcline            prefer [not] one line and an arc of max radius
  71      [!]arcsline           prefer [not] line between two arcs of min radius
  72      [!]loop               prefer [not] loop (arcsline, arc of same sense)
  73      [!]cross              prefer [not] cross (arcsline 2 senses, or twoarcs)
  74   if this doesn't resolve, will pick the shortest.
  75
  76  defobj|defpart O
  77  [commands]
  78  enddef
  79   Defines the object or part O.  Inside the definition, the commands
  80   do not draw when the object is being defined.  The object has its
  81   own coordinate space and its own location namespace.  `defpart'
  82   defines a `part', which is like an object except that:
  83    * showlibrary lists only parts, not objects
  84    * the -e and -E command line options distinguish parts and objects
  85
  86  part N [^]O [F [A]] [FR AR ...]
  87  obj[flip] O A F [P]
  88   Places an instance of object or part O.  The loc defined inside O as
  89   F (`formal parameter', F must be just <identifier>) is placed at
  90   existing loc A (`actual parameter').
  91
  92   Both objects (defined with defobj) and parts (defined with defpart)
  93   may be placed with either command !  Whether it's a part or an obj
  94   depends on the definition, not on the use - the use is just
  95   different syntaxes for the same kind of operation, and where the
  96   features offered by both `part' and `obj[flip]' overlap the
  97   behaviour is identical.
  98
  99   If `part N ^O' or `objflip' is used, rather than `part N O' or
 100   `obj', then the object is placed with object-space y coordinates
 101   negated (ie, it is mirrored so that the object's North exchanges
 102   with South).
 103
 104   For `part', each FR (`formal result') and AR (`actual result')
 105   specifies that the loc FR inside O is exported into the global
 106   namespace as a new loc AR.  Either FR or AR may start with `-'.
 107   Also, each loc L inside O is exported into the global namespace as a
 108   new loc N_L (unless N_L already exists).  If A is not specified then
 109   N_F is used.
 110
 111   For `obj[flip]' if prefix P (syntax is that of an identifier) is
 112   specified, each other loc L inside O is exported into the global
 113   namespace as a new loc PL (unless PL already exists).  P may be `='
 114   to indicate an empty prefix (default is not to export locs).
 115
 116 Command-line options
 117
 118  -D       turn on debug (level 1)  } currently only debug levels are
 119  -Dnnn    set debug level to nnn   }  0 (none) and 1 (some), default=0
 120
 121  -lL      output for layer L (digits, or `*' for any) (default: *)
 122
 123  -e<layersel>[ARSCcLlMNOm]...
 124           Turn on and off drawing of elements in groups.
 125           These are abbreviations for various -E... options.
 126             track                                                 -E....
 127               A  full track                                         ARSc
 128               R  rails only                                         aRsc
 129               S  rails and sleepers only                            aRSc
 130               C  centrelines only                                   arsC
 131               c  swept area and ticks only                          Arsc
 132               r  no lines drawn at all                              arcs
 133             labels at locs
 134               L  label top-level locs (turns on bars for them too)  LM
 135               l  do not label any locs                              l
 136             bars at locs (thick lines perp to track dir'n)
 137               M  bars for top-level locs only                       Mno
 138               N  bars for top-level locs and those in obj's         MNo
 139               O  bars for everything, including those inside parts  MNO
 140               m  no bars (turns off labelling too)                  mnol
 141
 142  -E<layersel>[ARSCLMNOarsclmno]...
 143           enable (capitals) or disable (lowercase) drawing of
 144           individual elements
 145               A  draw track swept area, with ticks
 146               R  draw track rails
 147               S  draw track sleepers
 148               C  draw track centrelines
 149               L  label locs
 150               M  mark locs with a bar
 151               N  mark locs with a bar in objs
 152               O  mark locs with a bar in parts
 153
 154  -q       quiet: do not print info to stderr
 155           (default: prints bounding box, at the moment)
 156
 157 <layersel> (for -e and -E) works as follows:
 158
 159  When file says `layer KL', default drawing element set is set
 160  depending on K and L (see description of `layer' command), using last
 161  specified -l layer.  Then all -e/-E options are scanned, in order,
 162  and each one that matches modifies the drawing element set.
 163
 164  <layersel> is GN[D][C][V].  It matches `layer KL' iff the glob
 165  pattern G (which may be empty) matches the whole of K, and layer
 166  restriction N[D]C matches L.  C is several identical `=', `+' or `-';
 167  D+ matches L iff L>=D; D++ iff L>D; D+++ iff L>D+1 and so on; D-
 168  matches L iff L<=D; D-- iff L<D; etc.; D= matches L iff L==D; D== iff
 169  D-1<=L<=D+1; D=== iff D-2<=L<=D+2; etc.  If D is omitted the current
 170  layer (from the most recent -l option) is used (or `5' if current
 171  layer is `*').  N may be empty or `~'; the latter simply inverts the
 172  sense of the match.  If C is omitted then `=' is assumed.  If the
 173  final output layer is `*' then we pretend, for the moment, that L was
 174  D.  N[D][C][V] may be N[=]* to match, or not match, all layers.
 175
 176  If V is present then C must be exactly one character and it is as if
 177  V (must be an integer) copies of C were specified.
 178
 179
 180 Special comments in PostScript:
 181
 182  %L cmd S C [A...]
 183        a command C with args A is read for execution in scope S
 184  %L point SL X Y A
 185        point L in scope S has coords X Y and angle A
 186  %L bbox width  W (L..R)
 187  %L bbox height H (B..T)
 188        bounding box, giving width W, height H, left L, right R,
 189        bottom B and top T.  Includes full swept area of track,
 190        but only at locs (so curves which bend outside bounding
 191        box don't get counted)
 192  %L bbox no locs, no bbox
 193        there were no locs, so there is no bounding box
 194        usu because input file was just obj defns and showlibrary
 195
 196  Scope S is
 197    O!    when defining object or part O
 198    N:T   scope T but inside part (introduced with `part') N      } when
 199    O::T  scope T but inside obj (introduced with `obj[flip]') O  } placing