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).

 layer K[L]
  K is layer kind (letters and `_', may be empty), L is a layer depth
  (digits, or `=' meaning current 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       L        result (description)     result (element letters)
    any     other    nothing                  -
    empty   current  default track            RLMNasco
    `s'     current  nothing (`silent')       -
    `l'     current  centrelines only         CLMNarso
    other   current  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 global
  namespace as a new loc AR.  Either FR or AR may start with `-'.
  Also, each loc L inside O is exported into the global 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 global
  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: *)

 -e<layersel>[ARSCcLlMNOm]...
          Turn on and off drawing of elements in groups.
          These are abbreviations for various -E... options.
	    track                                                 -E....
	      A  full track                                         ARSc
	      R  rails only                                         aRsc
	      S  rails and sleepers only                            aRSc
	      C  centrelines only                                   arsC
	      c  swept area and ticks only                          Arsc
              r  no lines drawn at all                              arcs
	    labels at locs
	      L  label top-level locs (turns on bars for them too)  LM
	      l  do not label any locs                              l
	    bars at locs (thick lines perp to track dir'n)
	      M  bars for top-level locs only                       Mno
	      N  bars for top-level locs and those in obj's         MNo
	      O  bars for everything, including those inside parts  MNO
	      m  no bars (turns off labelling too)                  mnol

 -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

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

<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.

 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

 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