Locations, angles, etc.

 Key type is a `loc', which is a named location (absolute, 2D) and
 direction (at the location).  Angles are generally positive
 anticlockwise; bearings are angles measured from East.  The origin is
 at the South-West.

Syntaxes
 New location
  <identifier>
  -<identifier>       reverse the sense (ie, 180 degrees off)
 Existing location
  <identifier>        simply the named location
  -<identifier>       reverse the sense (ie, 180 degrees off)
  O![-]<identifier>   the location from the specified object
                      in whatever coordinate system that object
                      happens to have
  ^O![-]<identifier>  the same, but the object is flipped
                      N-S first (see `part' and `objflip')
 Quantity (length/angle)
  <number>[<unit>]
  Angle units: d (degrees,default)  r (radians)
  Length units: mm (default)  cm  m
 Identifiers (of locs and objects) start with lc letter, then
 alphanums and underscores

Commands

 abs P X Y A
  Defines loc P given coordinates (distances) and absolute bearing

 rel F T [L R A]
  Defines loc T: start at loc F, go forward L, translate right R,
  turn left A (defaults are all 0).

 segment [K*] [[-]S0 D0 ...] [-]Sn
  Specifies that arcs and lines in layer kind K are part of subsegment
  Sn.  `-' preceding the segment indicates that the Q rail is on the
  left as the line is drawn; without `-' the T rail is on the left.

  If additional Di and Si are provided then each Si apart from the
  last is followed by a distance Di saying how much track it applies
  to; the first D0 of track is part of subsegment S0, the next D1 of
  track is part of the next subsegment S1, and so on, with the last
  subsegment Sn (without a distance restriction) being used for track
  beyond that.  Each segment command resets the distance counter, and
  it is not an error for there to be unused subsegment specs in a
  segment command.  For these distances, only track whose subsegment
  encoding is actually drawn counts.

  If a part or object is used, then the arcs and lines inside it are
  processed for subsegments as if they appeared directly.

  A subsegment is a specification of:
    * The named electrically separate track segment of which
      this track forms part.
    * If this track is part of one possible configuration of a
      junction or point, the moveable feature name and configuration
      number.  Any one junction or point is one moveable feature and
      must be associated with and form part of one track segment.
      Moveable segments must be entirely contained within objects or
      parts (ie, one moveable segment cannot span multiple parts).
      Configuration numbers should start at 0 and be allocated densely.

  Subsegment specs Si are
    N[/[MP]]
  where
    N is the segment name (alphanumeric, may be empty)
    M is the moveable feature name (alphabetic, nonempty)
    P is the moveable feature position (numeric, nonempty, 0-indexed)
  If N is empty and MP is omitted then / must be present.
  Underscore (`_') counts as a letter.

  If a segment command occurs in a part or object, N is appended to
  the N in force at the start of the part or object, and in this
  case the segment will be set back to the last one from the list
  in force when the object was entered, as if the object had merely
  drawn an infinite amount of track.

  At the start of processing at the toplevel, the empty-named fixed
  subsegment is in use.  The empty-named top-level segment indicates
  that the subsegment is unspecified, unknown or absent.  All segments
  defined by objects at whose invocation the empty-named top-level
  segment is in force, are also assigned to the empty segment.

 segmap S D ...

  Maps specified (sub)segments or moveable feature(s) S to
  consequently defined (sub)segments or moveable features D.  This is
  primarily intended so that parts' internal segment and feature names
  can be remapped to correspond to the layout naming scheme.

   S       D
   ----    ----
   N       N'     remaps an entire segment including all features
   N/M     M'     remaps a particular moveable feature; N is the
                    unmapped name (if applicable)

  The effect is that (sub)segments or features used in segment
  commands are translated when the segment command is read; the
  specified names (S) are those which the segment command would
  define.

  Where segmap is used outside a part or object, the mappings apply to
  the segment names which would result at the toplevel.  When segmap
  is used inside a part or object, the mappings apply to the segment
  names defined within the part (perhaps by its subparts).  Ie, the
  mapping operates on the segment names visible at the level at which
  segmap is used (and thus several segmaps at different levels may
  operate on a signal segment name, in sequence).

  Mappings in later segmap commands replace earlier mappings at the
  same level.

  The remapping may coalesce otherwise-distinct segments.

 layer K[L]
  K is layer kind (letters and `_', may be empty), L is a layer depth
  (digits, or `=' meaning current layer, or `*' meaning output layer;
  default for L is `='; default KL at start of file is `layer 5').
  Controls drawing style, by selecting appropriate parts of the track
  and locs to draw, according to element selection rules.  Default
  outcomes:
    K         result (description)     result (element letters)
    empty     default track            RLMNasco
    `s'       nothing (`silent')       -
    `l'       centrelines only         CLMNarso
    other     everything               ARSCLMNO

 extend F T len L [R]        length L
 extend F T upto U [R]       s.t. perpendicular at T passes through U
 extend F T ang A R          subtending directionally A
 extend F T uptoang A R      s.t. direction at T is A
 extend F T parallel U R     s.t. direction at T is same as at U
  Draws an arc or line from loc F, defining the other end as loc T.
  If length R specified, draws an arc of radius R; R +ve curves to the
  right; R -ve to the left.

 join F T R [S ...]
  Joins one existing loc, F, to another, T.  F's direction points to
  the new track; T's away - ie the added track leaves F in F's
  direction and arrives at T in T's direction.  R is the minimum curve
  radius allowed.  S selects from the available solutions, and may be
  any of the following
     long                  prefer longer length solution
     short                 prefer shorter length solution
     right|left            prefer mostly bending to the left resp. right
     beginright|beginleft  prefer first bend to the right
     endright|endleft      prefer final bend to the right
     [!]twoarcs            prefer [not] two circular arcs of equal radius
     [!]arcline            prefer [not] one line and an arc of max radius
     [!]arcsline           prefer [not] line between two arcs of min radius
     [!]loop               prefer [not] loop (arcsline, arc of same sense)
     [!]cross              prefer [not] cross (arcsline 2 senses, or twoarcs)
  if this doesn't resolve, will pick the shortest.

 defobj|defpart O
 [commands]
 enddef
  Defines the object or part O.  Inside the definition, the commands
  do not draw when the object is being defined.  The object has its
  own coordinate space and its own location namespace.  `defpart'
  defines a `part', which is like an object except that:
   * showlibrary lists only parts, not objects
   * the -e and -E command line options distinguish parts and objects

 part N [^]O [F [A]] [FR AR ...]
 obj[flip] O A F [P]
  Places an instance of object or part O.  The loc defined inside O as
  F (`formal parameter', F must be just <identifier>) is placed at
  existing loc A (`actual parameter').

  Both objects (defined with defobj) and parts (defined with defpart)
  may be placed with either command !  Whether it's a part or an obj
  depends on the definition, not on the use - the use is just
  different syntaxes for the same kind of operation, and where the
  features offered by both `part' and `obj[flip]' overlap the
  behaviour is identical.

  If `part N ^O' or `objflip' is used, rather than `part N O' or
  `obj', then the object is placed with object-space y coordinates
  negated (ie, it is mirrored so that the object's North exchanges
  with South).

  For `part', each FR (`formal result') and AR (`actual result')
  specifies that the loc FR inside O is exported into the calling
  namespace as a new loc AR.  Either FR or AR may start with `-'.
  Also, each loc L inside O is exported into the calling namespace as a
  new loc N_L (unless N_L already exists).  If A is not specified then
  N_F is used.

  For `obj[flip]' if prefix P (syntax is that of an identifier) is
  specified, each other loc L inside O is exported into the calling
  namespace as a new loc PL (unless PL already exists).  P may be `='
  to indicate an empty prefix (default is not to export locs).

Command-line options

 -D       turn on debug (level 1)  } currently only debug levels are
 -Dnnn    set debug level to nnn   }  0 (none) and 1 (some), default=0

 -lL      output for layer L (digits, or `*' for any) (default: *)

 -S<scale>    set scale divider to <scale> (default is 7.0, ie
              output is 1/7 actual size)

 -P<xp>x<yp>  output physical page (<xp>,<yp>).  xp and yp are
              integers specifying the number of pages to shift by
              in each direction.  xp is multiplied by 270mm; yp
              is multiplied by 190mm.

 -e<layersel>[ARSCcLlMNOm]...
          Turn on and off drawing of elements in groups.
          These are abbreviations for various -E... options.
            track                                                 -E....
              A  full track                                        ARScg
              R  rails only                                        aRscg
              S  rails and sleepers only                           aRScg
              C  centrelines only                                  arsCg
              c  swept area and ticks only                         Arscg
              r  no lines drawn at all                             arcs
            labels at locs
              L  label top-level locs (turns on bars for them too)  LMg
              l  do not label any locs                              l
            bars at locs (thick lines perp to track dir'n)
              M  bars for top-level locs only                       Mnog
              N  bars for top-level locs and those in obj's         MNog
              O  bars for everything, including those inside parts  MNOg
              m  no bars (turns off labelling too)                  mnol
            subsegment encoding
              G  draw only subsegment encoding                 Garcslmno

 -E<layersel>[ARSCLMNOarsclmno]...
          enable (capitals) or disable (lowercase) drawing of
          individual elements
              A  draw track swept area, with ticks
              R  draw track rails
              S  draw track sleepers
              C  draw track centrelines
              L  label locs
              M  mark locs with a bar
              N  mark locs with a bar in objs
              O  mark locs with a bar in parts
              G  draw subsegment encoding

 -q       quiet: do not print info to stderr
          (default: prints bounding box, at the moment)

[-GL      output segment colour map request list                     ]
[         use with -eG or -EG to write out the list of subsegment    ]
[         specs which will need colours, one per line (and not       ]
[         necessarily only once each)                                ]
 -GL, -GR, -GP are to do with segment encoding and subsegment specs
  and that kind of thing.  The comment above is the most useful
  documentation and is out of date.  See also layout's argument
  parser, segencolayers.gen-make, Makefile, segcmap.h, segcmapassign,
  etc.

<layersel> (for -e and -E) works as follows:

 When file says `layer KL', default drawing element set is set
 depending on K and L (see description of `layer' command), using last
 specified -l layer.  Then all -e/-E options are scanned, in order,
 and each one that matches modifies the drawing element set.

 <layersel> is GN[D][C][V].  It matches `layer KL' iff the glob
 pattern G (which may be empty) matches the whole of K, and layer
 restriction N[D]C matches L.  C is several identical `=', `+' or `-';
 D+ matches L iff L>=D; D++ iff L>D; D+++ iff L>D+1 and so on; D-
 matches L iff L<=D; D-- iff L<D; etc.; D= matches L iff L==D; D== iff
 D-1<=L<=D+1; D=== iff D-2<=L<=D+2; etc.  If D is omitted the current
 layer (from the most recent -l option) is used (or `5' if current
 layer is `*').  N may be empty or `~'; the latter simply inverts the
 sense of the match.  If C is omitted then `=' is assumed.  If the
 final output layer is `*' then we pretend, for the moment, that L was
 D.  N[D][C][V] may be N[=]* to match, or not match, all layers.

 If V is present then C must be exactly one character and it is as if
 V (must be an integer) copies of C were specified.


Special comments in PostScript:

 %L cmd S C [A...]
       a command C with args A is read for execution in scope S
 %L point SL X Y A
       point L in scope S has coords X Y and angle A
 %L bbox width  W (L..R)
 %L bbox height H (B..T)
       bounding box, giving width W, height H, left L, right R,
       bottom B and top T.  Includes full swept area of track,
       but only at locs (so curves which bend outside bounding
       box don't get counted)
 %L bbox no locs, no bbox
       there were no locs, so there is no bounding box
       usu because input file was just obj defns and showlibrary
 %L segmentpart I KL [-]S D X0 Y0 A0 X1 Y1 A1
       records that a piece of subsegment S is drawn in the subsegment
       encoding.  The piece is of length D, in layer KL (which may be
       the empty string, depending on layer configurations), and runs
       from the loc X0,Y0,A0 to X1,Y1,A1.  I is a counter which starts
       at 0 and is simply there to help cross-reference between
       various programs and formats.

 Scope S is
   O!    when defining object or part O
   N:T   scope T but inside part (introduced with `part') N      } when
   O::T  scope T but inside obj (introduced with `obj[flip]') O  } placing


See also:
 layout-data.h for info regarding layout data deliverables for use by
                 control and UI software
 redactgraph.c, extractgraph for info regarding extraction and
                  preparation of those deliverables