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  segment [K*] [S0 D0 ...] Sn
  37   Specifies that arcs and lines in layer kind K are part of subsegment
  38   Sn.
  39
  40   If additional Di and Si are provided then each Si apart from the
  41   last is followed by a distance Di saying how much track it applies
  42   to; the first D0 of track is part of subsegment S0, the next D1 of
  43   track is part of the next subsegment S1, and so on, with the last
  44   subsegment Sn (without a distance restriction) being used for track
  45   beyond that.  Each segment command resets the distance counter, and
  46   it is not an error for there to be unused subsegment specs in a
  47   segment command.  For these distances, only track whose subsegment
  48   encoding is actually drawn counts.
  49
  50   If a part or object is used, then the arcs and lines inside it are
  51   processed for subsegments as if they appeared directly.
  52
  53   A subsegment is a specification of:
  54     * The named electrically separate track segment of which
  55       this track forms part.
  56     * If this track is part of one possible configuration of a
  57       junction or point, the moveable feature name and configuration
  58       number.  Any one junction or point is one moveable feature and
  59       must be associated with and form part of one track segment.
  60       Moveable segments must be entirely contained within objects or
  61       parts (ie, one moveable segment cannot span multiple parts).
  62       Configuration numbers should start at 0 and be allocated densely.
  63
  64   Subsegment specs Si are
  65     N[/[MP]]
  66   where
  67     N is the segment name (alphanumeric, may be empty)
  68     M is the moveable feature name (alphabetic, nonempty)
  69     P is the moveable feature position (numeric, nonempty, 0-indexed)
  70   If N is empty and MP is omitted then / must be present.
  71
  72   If a segment command occurs in a part or object, N is appended to
  73   the N in force at the start of the part or object.  (Note that it is
  74   not usually a good idea to rely on how a complex object leaves the
  75   setting of the segment, as probably the calling code will end up
  76   using the object's segment names.)
  77
  78   At the start of processing at the toplevel, the empty-named fixed
  79   subsegment is in use.  The empty-named top-level subsegment
  80   indicates that the subsegment is unspecified, unknown or absent.
  81
  82  segmap S D ...
  83
  84   Maps specified (sub)segments or moveable feature(s) S to
  85   consequently defined (sub)segments or moveable features D.  This is
  86   primarily intended so that parts' internal segment and feature names
  87   can be remapped to correspond to the layout naming scheme.
  88
  89    S       O
  90    ----    ----
  91    N       N'     remaps an entire segment including all features
  92    N/M     M'     remaps a particular moveable feature; N is the
  93                     unmapped name (if applicable)
  94
  95   The effect is that (sub)segments or features used in segment
  96   commands are translated when the segment command is read; the
  97   specified names (S) are those which the segment command would
  98   define.
  99
 100   Where segmap is used outside a part or object, the mappings apply to
 101   the segment names which would result at the toplevel.  When segmap
 102   is used inside a part or object, the mappings apply to the segment
 103   names defined within the part (perhaps by its subparts).  Ie, the
 104   mapping operates on the segment names visible at the level at which
 105   segmap is used (and thus several segmaps at different levels may
 106   operate on a signal segment name, in sequence).
 107
 108   Mappings in later segmap commands replace earlier mappings at the
 109   same level.
 110
 111   The remapping may coalesce otherwise-distinct segments.
 112
 113  layer K[L]
 114   K is layer kind (letters and `_', may be empty), L is a layer depth
 115   (digits, or `=' meaning current layer, or `*' meaning output layer;
 116   default for L is `='; default KL at start of file is `layer 5').
 117   Controls drawing style, by selecting appropriate parts of the track
 118   and locs to draw, according to element selection rules.  Default
 119   outcomes:
 120     K         result (description)     result (element letters)
 121     empty     default track            RLMNasco
 122     `s'       nothing (`silent')       -
 123     `l'       centrelines only         CLMNarso
 124     other     everything               ARSCLMNO
 125
 126  extend F T len L [R]        length L
 127  extend F T upto U [R]       s.t. perpendicular at T passes through U
 128  extend F T ang A R          subtending directionally A
 129  extend F T uptoang A R      s.t. direction at T is A
 130  extend F T parallel U R     s.t. direction at T is same as at U
 131   Draws an arc or line from loc F, defining the other end as loc T.
 132   If length R specified, draws an arc of radius R; R +ve curves to the
 133   right; R -ve to the left.
 134
 135  join F T R [S ...]
 136   Joins one existing loc, F, to another, T.  F's direction points to
 137   the new track; T's away - ie the added track leaves F in F's
 138   direction and arrives at T in T's direction.  R is the minimum curve
 139   radius allowed.  S selects from the available solutions, and may be
 140   any of the following
 141      long                  prefer longer length solution
 142      short                 prefer shorter length solution
 143      right|left            prefer mostly bending to the left resp. right
 144      beginright|beginleft  prefer first bend to the right
 145      endright|endleft      prefer final bend to the right
 146      [!]twoarcs            prefer [not] two circular arcs of equal radius
 147      [!]arcline            prefer [not] one line and an arc of max radius
 148      [!]arcsline           prefer [not] line between two arcs of min radius
 149      [!]loop               prefer [not] loop (arcsline, arc of same sense)
 150      [!]cross              prefer [not] cross (arcsline 2 senses, or twoarcs)
 151   if this doesn't resolve, will pick the shortest.
 152
 153  defobj|defpart O
 154  [commands]
 155  enddef
 156   Defines the object or part O.  Inside the definition, the commands
 157   do not draw when the object is being defined.  The object has its
 158   own coordinate space and its own location namespace.  `defpart'
 159   defines a `part', which is like an object except that:
 160    * showlibrary lists only parts, not objects
 161    * the -e and -E command line options distinguish parts and objects
 162
 163  part N [^]O [F [A]] [FR AR ...]
 164  obj[flip] O A F [P]
 165   Places an instance of object or part O.  The loc defined inside O as
 166   F (`formal parameter', F must be just <identifier>) is placed at
 167   existing loc A (`actual parameter').
 168
 169   Both objects (defined with defobj) and parts (defined with defpart)
 170   may be placed with either command !  Whether it's a part or an obj
 171   depends on the definition, not on the use - the use is just
 172   different syntaxes for the same kind of operation, and where the
 173   features offered by both `part' and `obj[flip]' overlap the
 174   behaviour is identical.
 175
 176   If `part N ^O' or `objflip' is used, rather than `part N O' or
 177   `obj', then the object is placed with object-space y coordinates
 178   negated (ie, it is mirrored so that the object's North exchanges
 179   with South).
 180
 181   For `part', each FR (`formal result') and AR (`actual result')
 182   specifies that the loc FR inside O is exported into the global
 183   namespace as a new loc AR.  Either FR or AR may start with `-'.
 184   Also, each loc L inside O is exported into the global namespace as a
 185   new loc N_L (unless N_L already exists).  If A is not specified then
 186   N_F is used.
 187
 188   For `obj[flip]' if prefix P (syntax is that of an identifier) is
 189   specified, each other loc L inside O is exported into the global
 190   namespace as a new loc PL (unless PL already exists).  P may be `='
 191   to indicate an empty prefix (default is not to export locs).
 192
 193 Command-line options
 194
 195  -D       turn on debug (level 1)  } currently only debug levels are
 196  -Dnnn    set debug level to nnn   }  0 (none) and 1 (some), default=0
 197
 198  -lL      output for layer L (digits, or `*' for any) (default: *)
 199
 200  -S<scale>    set scale divider to <scale> (default is 7.0, ie
 201               output is 1/7 actual size)
 202
 203  -P<xp>x<yp>  output physical page (<xp>,<yp>).  xp and yp are
 204               integers specifying the number of pages to shift by
 205               in each direction.  xp is multiplied by 270mm; yp
 206               is multiplied by 190mm.
 207
 208  -e<layersel>[ARSCcLlMNOm]...
 209           Turn on and off drawing of elements in groups.
 210           These are abbreviations for various -E... options.
 211             track                                                 -E....
 212               A  full track                                        ARScg
 213               R  rails only                                        aRscg
 214               S  rails and sleepers only                           aRScg
 215               C  centrelines only                                  arsCg
 216               c  swept area and ticks only                         Arscg
 217               r  no lines drawn at all                             arcs
 218             labels at locs
 219               L  label top-level locs (turns on bars for them too)  LMg
 220               l  do not label any locs                              l
 221             bars at locs (thick lines perp to track dir'n)
 222               M  bars for top-level locs only                       Mnog
 223               N  bars for top-level locs and those in obj's         MNog
 224               O  bars for everything, including those inside parts  MNOg
 225               m  no bars (turns off labelling too)                  mnol
 226             subsegment encoding
 227               G  draw only subsegment encoding                 Garcslmno
 228
 229  -E<layersel>[ARSCLMNOarsclmno]...
 230           enable (capitals) or disable (lowercase) drawing of
 231           individual elements
 232               A  draw track swept area, with ticks
 233               R  draw track rails
 234               S  draw track sleepers
 235               C  draw track centrelines
 236               L  label locs
 237               M  mark locs with a bar
 238               N  mark locs with a bar in objs
 239               O  mark locs with a bar in parts
 240               G  draw subsegment encoding
 241
 242  -GL      output segment colour map request list
 243           use with -eG or -EG to write out the list of subsegment
 244           specs which will need colours, one per line (and not
 245           necessarily only once each)
 246
 247  -q       quiet: do not print info to stderr
 248           (default: prints bounding box, at the moment)
 249
 250 <layersel> (for -e and -E) works as follows:
 251
 252  When file says `layer KL', default drawing element set is set
 253  depending on K and L (see description of `layer' command), using last
 254  specified -l layer.  Then all -e/-E options are scanned, in order,
 255  and each one that matches modifies the drawing element set.
 256
 257  <layersel> is GN[D][C][V].  It matches `layer KL' iff the glob
 258  pattern G (which may be empty) matches the whole of K, and layer
 259  restriction N[D]C matches L.  C is several identical `=', `+' or `-';
 260  D+ matches L iff L>=D; D++ iff L>D; D+++ iff L>D+1 and so on; D-
 261  matches L iff L<=D; D-- iff L<D; etc.; D= matches L iff L==D; D== iff
 262  D-1<=L<=D+1; D=== iff D-2<=L<=D+2; etc.  If D is omitted the current
 263  layer (from the most recent -l option) is used (or `5' if current
 264  layer is `*').  N may be empty or `~'; the latter simply inverts the
 265  sense of the match.  If C is omitted then `=' is assumed.  If the
 266  final output layer is `*' then we pretend, for the moment, that L was
 267  D.  N[D][C][V] may be N[=]* to match, or not match, all layers.
 268
 269  If V is present then C must be exactly one character and it is as if
 270  V (must be an integer) copies of C were specified.
 271
 272
 273 Special comments in PostScript:
 274
 275  %L cmd S C [A...]
 276        a command C with args A is read for execution in scope S
 277  %L point SL X Y A
 278        point L in scope S has coords X Y and angle A
 279  %L bbox width  W (L..R)
 280  %L bbox height H (B..T)
 281        bounding box, giving width W, height H, left L, right R,
 282        bottom B and top T.  Includes full swept area of track,
 283        but only at locs (so curves which bend outside bounding
 284        box don't get counted)
 285  %L bbox no locs, no bbox
 286        there were no locs, so there is no bounding box
 287        usu because input file was just obj defns and showlibrary
 288
 289  Scope S is
 290    O!    when defining object or part O
 291    N:T   scope T but inside part (introduced with `part') N      } when
 292    O::T  scope T but inside obj (introduced with `obj[flip]') O  } placing