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)
+ 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
extend F T ang A R subtending directionally A
[!]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
with South).
For `part', each FR (`formal result') and AR (`actual result')
- specifies that the loc FR inside O is exported into the global
+ 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 global namespace as a
+ 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 global
+ 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)
+ -Dnnn set debug level to nnn } 0 (none) and 1 (some), default=0
+
+ -lL output for layer L (digits, or `*' for any) (default: *)
- -e[ARSCcLlMNOm]...
+ -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 ARSc
- R rails only aRsc
- S rails and sleepers only aRSc
- C centrelines only arsC
- c swept area and ticks only Arsc
- 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[ARSCLMNOarsclmno]...
+ 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
- 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
+ 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)
- Default is -d0, -EaRscLMNo, not quiet.
+[-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 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