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