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