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