Syntaxes
New location
<identifier>
+ -<identifier> reverse the sense (ie, 180 degrees off)
Existing location
- [-]<identifier> (- means reverse the sense)
+ <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)
abs P X Y A
Defines loc P given coordinates (distances) and absolute bearing
- rel F T L R A
+ rel F T [L R A]
Defines loc T: start at loc F, go forward L, translate right R,
- turn left A.
+ 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)
+ N/[MP] N'/[M'P'] remaps a specific moveable feature position to a
+ specific other moveable feature position;
+ empty M and M' mean the fixed portions.
+
+ 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
[!]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 O
+ defobj|defpart O
[commands]
enddef
- Defines the object 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.
+ 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 O. The loc defined inside O as F
- (`formal parameter', F must be just <identifier>) is placed at
- existing loc A (`actual parameter'). 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. If `flip' is used then
- the object is placed with object-space y coordinates negated (ie, it
- is mirrored so that the object's North exchanges with South).
+ 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).
+
+ segcmap S P...
+ Map segment S to colours using postscript commands P... (which
+ should be a postscript fragment to modify the graphics state,
+ typically `N setgray' or the like. This is used for the drawing
+ element Q (see below). S should be the bare segment (no movfeat or
+ `-').
+
+ segend L S
+ Notes that segment S (which should not specify a movfeat but may
+ specify `-') has an end at location L. This is fed back from
+ extractgraph's run on a previous result of running layout, and used
+ to determine where to place the segment labels for E. NOT YET
+ IMPLEMENTED
+
+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>[ARSCcLlDdMNOm]...
+ Turn on and off drawing of elements in groups.
+ These are abbreviations for various -E... options.
+ track -E.....
+ A full track ARScgd
+ R rails only aRscgD
+ S rails and sleepers only aRScgd
+ C centrelines only arsCgd
+ c swept area and ticks only Arscgd
+ r no lines drawn at all arsc
+ labels at locs
+ L label top-level locs (turns on bars for them too) LMg
+ l do not label any locs l
+ label distances
+ D label all distances D
+ d do not label any distances
+ 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>[ARSCLDMNOarscldmno]...
+ enable (capitals) or disable (lowercase) drawing of
+ individual elements
+ A draw track swept area, with ticks
+ R draw track rails
+ Q draw track segment fills according to segcmap
+ E label track segments according to segend
+ S draw track sleepers
+ C draw track centrelines
+ L label locs
+ D label distances along the track
+ 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
~ijackson / trains.git / blobdiff