Update upstream source from tag 'upstream/5.1.0'

Update to upstream version '5.1.0'
with Debian dir 93ca74b8b4602fce4c9c7740e0cfdde25f086673

1 files changed, 251 insertions, 42 deletions

diff --git a/app/doc/changem.but b/app/doc/changem.but
index 2bcd90b..c8cb189 100644
--- a/app/doc/changem.but
+++ b/app/doc/changem.but
@@ -20,7 +20,7 @@ The \f{Change Menu} has all functions related to modifying objects that exist on
 
 \u000
 
-\dd \f{Connect Sectional Tracks} - creates a connection between sectional track pieces by slightly moving the select piece(s) and the pieces they connect to.
+\dd \f{Connect Two Tracks} - creates a connection between track pieces with an option to slightly move the select piece(s) and the pieces they connect to. (\K{cmdConnect}).
 
 \u000
 
@@ -28,39 +28,43 @@ The \f{Change Menu} has all functions related to modifying objects that exist on
 
 \u000
 
-\dd \f{Flip} - turn selected object(s) over or around.
+\dd \f{Flip} - turn selected object(s) over or around. (\K{cmdFlip}).
 
 \u000
 
-\dd \f{Join} - connect two separate pieces of track. This command can be used to move one of the pieces of track to the endpoint of the other or to create a connection by laying a stretch of flex-track.
+\dd \f{Join} - connect two separate pieces of track. This command can be used to move one of the pieces of track to the endpoint of the other or to create a connection by laying a stretch of flex-track. (\K{cmdJoin}).
 
 \u000
 
-\dd \f{Modify} - modify an existing track.
+\dd \f{Modify} - modify an existing track, or lines. (\K{cmdModify}).
 
 \u000
 
-\dd \f{Move} - move selected object(s). 
+\dd \f{Move} - move selected object(s). (\K{cmdMove}).
 
 \u000
 
-\dd \f{Move Description} - move the endpoint description of a track piece to another location.
+\dd \f{Move Description} - move the endpoint description of a track piece to another location. (\K{cmdMoveLabel}).
 
 \u000
 
+\dd \f{Pan/Zoom} - move or resize the viewport using the mouse.
+
+\u000   
+
 \dd \f{Profile} - display the elevation profile of a definable stretch of track (\K{cmdProfile}).
 
 \u000
 
-\dd \f{Properties} - sets \e{XTrackCAD} into \e{Describe} mode. Whenever an object is clicked on while in this mode, the \f{Properties} dialog is opened. This dialog allows direct manipulation of settings such as the objects length, position or orientation.
+\dd \f{Properties} - sets \e{XTrackCAD} into \e{Describe} mode. Whenever an object is clicked on while in this mode, the \f{Properties} dialog is opened. This dialog allows direct manipulation of settings such as the objects length, position or orientation. (\K{cmdDescribe}).
 
 \u000
 
-\dd \f{Raise/Lower Elevations} - raise or lower elevation of selected tracks.
+\dd \f{Raise/Lower Elevations} - raise or lower elevation of selected tracks. (\K{cmdRaiseElev}).
 
 \u000
 
-\dd \f{Rotate} - rotate selected object(s).
+\dd \f{Rotate} - rotate selected object(s). (\K{cmdRotate}).
 
 \u000
 
@@ -68,11 +72,11 @@ The \f{Change Menu} has all functions related to modifying objects that exist on
 
 \u000
 
-\dd \f{Select} - sets \e{XTrackCAD} into \e{Select} mode.  Whenever an object is clicked on while in this mode, this selection state of this object is reversed.  If an object was unselected it becomes selected, and vice versa. To unselect all objects press the ESC key, use \f{Deselect All} from the \f{Edit} (\K{editM}) menu or \f{Deselect All} from the \f{Pop-up} menu (\K{mouseBcmd}).
+\dd \f{Select} - sets \e{XTrackCAD} into \e{Select} mode.  Whenever an object is clicked on while in this mode, this selection state of this object is reversed.  If an object was unselected it becomes selected, and vice versa. To unselect all objects press the ESC key, use \f{Deselect All} from the \f{Edit} (\K{editM}) menu or \f{Deselect All} from the \f{Pop-up} menu (\K{mouseBcmd}). (\K{cmdSelect}).
 
 \u000
 
-\dd \f{Split Track} - the \f{Split Track} command can be used in one of two ways;
+\dd \f{Split Track} - the \f{Split Track} (\K{cmdSplitTrack}) command can be used in one of two ways;
 
 \lcont{
 
@@ -115,17 +119,27 @@ Using the \f{Select} command, select the track that is to have its elevation set
 \rule
 
 
-\S{cmdConnect} Connect Sectional Tracks
+\S{cmdConnect} Connect Tracks
 
 \G{png.d/bconnect.png}
 
-This command is used exclusively with \e{Sectional Track}.
+This command is frequently used with \e{Sectional Track}.  But it can be useful to reattach ordinary track which has become disconected or split.
+
+There are three modes, 
+
+\u000
+
+\b a \f{Left} click on a track near a disconnected end-point followed by a second on a close-by disconnected end-point on another track will try to join two tracks
 
-Occasionally pieces of sectional track do not line up exactly, especially when creating figure-8's or passing sidings.  When laying out the actual track you can compensate for this by adjusting the individual tracks to provide a bit of slack.  This command simulates that process.
+\b a \f{Shift-Left} click on a connected track will "Tighten Tracks" moving other tracks connected to this track to reduce any small distance or angle differences  
 
-Click on the endpoint of each track you're trying to connect.  Tracks will move slightly in an attempt to overcome the gap.  If the gap is too large, the connection will fail. If this occurs, try using other track pieces in your layout.
+\b selecting a set of tracks followed by a \f{Right} click will prompt for confirmation that all selected tracks with unconnected endpoints should be joined to nearby selected track at an unconnected end point. This mode allows for an entire layout to be reconnected after a Select-All.  
 
-\e{XTrackCAD} adjusts the positions of tracks connected to the tracks up to a track with more than two connections.  See the Demo for details.
+\f{Notes for two track mode:} Occasionally pieces of sectional track do not line up exactly, especially when creating figure-8's or passing sidings. When laying out the actual track you can compensate for this by adjusting the individual tracks to provide a bit of slack.  This command simulates that process.
+
+Click on the endpoint of each track you're trying to connect.  XtrkCAD will move the tracks slightly in an attempt to overcome the gap. If the gap is too large, the connection will fail. If this occurs, try using other track pieces in your layout.
+
+\e{XTrackCAD} adjusts the positions of tracks connected to the tracks up to a track with more than two connections. See the Demo for details.
 
 If one (or both) the selected tracks is an adjustable section (such as Kato's Adjustable Track #20-050) then the length of the track is changed to fill the gap.
 
@@ -160,7 +174,7 @@ An endpoint can have one of several elevation types:
 
 \b \f{Station} - assigns a name to the endpoint.
 
-\f{Note:} Only one of these attributes can be assigned to an endpoint.  For example, an endpoint can not be defined as a Grade and a Station at the same time.
+\f{Note:} Only one of these attributes can be assigned to an endpoint. For example, an endpoint can not be defined as a Grade and a Station at the same time.
 
 When an endpoint is selected on the layout by \e{Left-Click}, it is highlighted by a large red dot and its elevation type and values are displayed in the dialog.
 
@@ -266,7 +280,9 @@ For detail about;
 
 \S2{joinTrackCurve} Using Curved Flex-Track
 
-This method of joining track may be used where tracks are joined with a 'simple curve', e.g. one which uses a curve in a single direction as opposed to using reverse curves (\K{generalTerms}).
+This method of joining track may be used using Normal Easments where tracks are either joined with a 'simple curve'\k{joinNormalEasment}, e.g. one which uses a curve in a single direction as opposed to using reverse curves (\K{generalTerms}) or using complex curves if Easement is set to Cornu \K{joinCornu}.
+
+\S2{joinNormalEasment} Join with Normal Easement
 
 \u000
 
@@ -344,6 +360,63 @@ For detail about;
 
 \dd Moving one segment of track to join with another refer to \K{joinTrackMove}.
 
+\S2{joinCornu} \i{Creating a Cornu} \i{Cornu Easements} Join with Cornu Easement
+
+\u000
+
+\n First, ensure that the Easement type option is set to Cornu - see \k{cmdEasement}
+
+\n Start the join process by clicking on the Join button (\G{png.d/bjoin.png}).
+
+\lcont{
+
+\u000
+
+\G{png.d/joincornu1.png}
+
+\u000
+
+}
+
+\dd \e{Left-Click} the open endpoint of one of the two tracks being joined. A red dot within a red circle will appear at the end of the join.
+
+\u000
+
+\dd \e{Left-Drag} the endpoint to where you want it and release the button. The point will only move along the piece of track with the open endpoint (if this track type can be split) as far as the opposite end, or as an extension of that track at the selected end with the same curvature (if this track can be extended). Note that you will be able to fine-tune the end positions later.
+
+\lcont{
+
+\u000
+
+\G{png.d/joincornu2.png}
+
+\u000
+
+}
+
+\dd \e{Left-Click} the endpoint of the other track being joined. Another red dot within a circle will appear at that end of the join.
+
+\u000
+
+\dd \e{Left-Drag} the endpoint to where you want it and release the button. The second endpoint can only be moved along the second track as far as the other end (if it can be split) or as an extension beyond the end of this track (if it can be extended). The initial curve will be drawn - it will be red if the minimum radius is smaller than the minimum radius option.
+
+\lcont{
+
+\u000
+
+\G{png.d/joincornu3.png}
+
+\u000
+
+}
+
+\dd You are now in "Select Points" mode. You can select one end point at a time with \e{Left-Click} and move it with \e{Left-Drag}.
+
+\u000
+
+\dd Once you are happy, hit \e{Enter} or the \e{SpaceBar} to finish editing the easement. Or hit \e{Esc} to cancel. 
+
+\dd If you want to modify the Cornu later (even if it is joined at both ends) see \k{chgCornu}
 
 \rule
 
@@ -396,7 +469,7 @@ Any tracks created during the \f{Join} command will have the following propertie
 
 Turnouts and Sectional (\K{cmdHotBar}) tracks can be joined to other tracks. \e{XTrackCAD} extends the selected endpoint with a straight track when making the connection.  
 
-A Turntable (\K{cmdTurntable}) can be joined however it must be used as the second endpoint.
+A Turntable (\K{cmdTurntable}) can be joined however it must be used as the second endpoint for normal easements but can be connected to either end with Cornu.
 
 For detail about;
 
@@ -473,17 +546,19 @@ For detail about;
 
 \G{png.d/bmodify.png}
 
-The \f{Modify} command is used to change characteristics of or extend existing track by adding new track. This command works with any unconnected track endpoint.
+The \f{Modify} command is used to change characteristics of or extend existing track by adding new track. This command works with any unconnected track endpoint, or with a \e{Cornu} or \e{Bezier} track even if connected
 
 The \f{Modify} command can be invoked using the \f{Change>Modify} menu item, the \f{Modify} button or the menu raised by a \e{Right-Click} over the \f{Main Canvas}.
 
 Either the left mouse button (for changing length or creating a tangent track) or the right mouse button (for extending with a new track) is used to modify the unconnected endpoint.
 
-The endpoints of a \e{Line}, \e{Dimension Line}, \e{Table Edge} or \e{Bench-work} can be dragged to new positions.  A \e{Box} is treated as 4 Lines.
+The endpoints of a \e{Line}, \e{Dimension Line}, \e{Table Edge} or \e{Bench-work} can be dragged to new positions.  A \e{Box} or a \e{FilledBox} can be modified by selecting a corner and dragging in two dimensions, or a side and dragging it orthogonally. These modifications preserve a 4-sided rectangle.
+
+The controlpoints of a \e{Cornu Track}, \e{Bezier Track} or \e{Bezier Line} can be changed.
 
 \e{Curved Lines} are modified in same manner as curved track.
 
-Selecting a corner of a \e{Poly Line}, \e{Filled Box} or \e{Polygon} moves that corner to a new position, and if moved close to a neighboring corner will merge the two corners and delete the edge between them. Selecting an edge will create a corner that can be dragged to a new position.
+Selecting a corner of a \e{Poly Line} or \e{Polygon} moves that corner to a new position, and if moved close to a neighboring corner will merge the two corners and delete the edge between them. Selecting an edge will create a corner that can be dragged to a new position.
 
 Any tracks created during the \f{Modify} command will have the following properties inherited from the first track: selected state, hidden state, scale, track gauge and Layer. 
 
@@ -503,6 +578,14 @@ For detail about;
 
 \dd Extending track length refer to \K{extendTrack}
 
+\u000
+
+\dd Modifying a Cornu refer to \K{chgCornu}
+
+\u000
+
+\dd Modifying a Bezier refer to \K{chgBezier}
+
 \rule
 
 
@@ -633,6 +716,57 @@ For detail about;
 
 \rule
 
+\S2{chgCornu} \i{Cornu Easements} Modifying a Cornu
+
+Because a Cornu is defined by its end points position, angle and radius - it can only be directly modified by dragging an end point along a track. 
+
+\n Click the \f{Modify} button (\G{png.d/bmodify.png}) to activate the \f{Modify} function.
+
+\lcont{\u000}
+
+\n Click on the Cornu track. The track ends will turn into roundels
+
+\lcont{\u000}
+
+\n \e{Left-Click} the endpoint and \e{Left-Drag} it to move the endpoint along the connected track, or beyond it if you want that track extended ( but this only works in the direction of the Cornu).
+
+\lcont{\u000}
+
+\n Repeat with the other end-pint if desired
+
+\lcont{\u000}
+
+\n Once you are happy, hit the \e{spacebar} or \e{Enter}, or to cancel hit \e{Escape}.
+
+\f{Note:} A Cornu can also be modified by moving or rotating a connected track.  
+
+\rule
+
+\S2{chgBezier} Modifying a Bezier
+
+Because a Bezier is defined by its control points position - its shape can only be modified by dragging an control point.
+
+\n Click the \f{Modify} button (\G{png.d/bmodify.png}) to activate the \f{Modify} function.
+
+\lcont{\u000}
+
+\n Click on the track. The control points will appear
+
+\lcont{\u000}
+
+\n \e{Left-Click} a control point and \e{Left-Drag} it to move it.
+
+\lcont{\u000}
+
+\n Repeat for another end point if desired
+
+\lcont{\u000}
+
+\n Once you are happy, hit the \e{spacebar} or \e{Enter}, or to cancel hit \e{Escape}.
+
+\f{Note: } A Bezier's end point will only be modifyable if it is not connected. Both internal control points can be modified even if the track is connected.
+
+\rule
 
 \S{cmdMove} Move
 
@@ -645,13 +779,21 @@ The \f{Move} command can be invoked using the \f{Change>Move} menu item or the \
 
 Successful use of this command requires selection of the object(s) to be moved before attempting to move it. An object is selected by using the \e{Left-Click} command. A group of connected objects can be selected using the \e{Shift+Left-Click} command.
 
-A pop-up menu with commands controlling how objects are drawn during moves can be activated by entering a \e{Shift+Right-Click} command while hovering over the \f{Main Canvas}
+A move can be achieved using one of the following methods;
 
-\G{png.d/mmovedraw.png}
+\u000
 
-\e{Left+Drag} is used to move the selected object(s) around the layout.
+\dd \e{Left+Drag} using the mouse. See \K{moveByMouse} for detail.
 
-\f{Note:} The \f{Draw Moving Tracks} Radio box on the \f{Command Options} (\K{cmdCmdopt}) dialog can also be used to select how objects are drawn during drags to move or rotate objects. The options for this feature are:
+\u000
+
+\dd Selecting fixed or specified amounts of translation in the X and Y directions using a \e{Right-Click} menu. See \K{moveByMenu} for detail.
+
+\u000
+
+\rule
+
+A pop-up menu with commands controlling how objects are drawn during moves can be activated by entering a \e{Shift+Right-Click} command while hovering over the \f{Main Canvas}
 
 \b \f{Normal} - objects are drawn normally. This can be time-consuming when using a slow machine and moving a large number of objects.
 
@@ -663,6 +805,54 @@ A pop-up menu with commands controlling how objects are drawn during moves can b
 
 \b \f{Endpoints} - only the endpoints are drawn (as stars).
 
+\G{png.d/mmovedraw.png}
+
+\rule
+
+\f{Note:} If the moved track is connected but the track it is connect to is not moved, it will be disconnected, unless that track or the last selected track is a Cornu, in which case the Cornu concenred will be modified (if possible) to remain connected. 
+
+\f{Note:} Cornu tracks connected to a turntable will be modified if it is moved or rotated. They remain connected at the point on the radius where they started, so it may be desireable to delete and redraw them if the rotation is large.
+
+\f{Note:} The \f{Draw Moving Tracks} Radio box on the \f{Command Options} (\K{cmdCmdopt}) dialog can also be used to select how objects are drawn during drags to move or rotate objects. The options for this feature are:
+
+\rule
+
+\S2{moveByMouse} Using Mouse
+
+Once object(s) are selected, \e{Left+Drag} is used to move them around the layout using the mouse. 
+
+Alternatively, \e{Shift+Ctrl+Arrow} can be used to micro-move the selected object(s). The amount micro-moved is dependent on the zoom in use. To move by smaller increments, zoom in further. My moving to macro-zoom modes extremely fine adjustments can be made.
+
+Remember that unattached objects can also be moved to exact positions using the \K{cmdDescribe} Command or by the \K{moveByMenu}. 
+
+\S2{moveByMenu} Using Values of X and Y Translation
+
+Move An Object Using Fixed or Specified amounts of X and Y Translation.
+
+A pop-up menu with additional menu items allows you to \f{Move} the selected object(s) through through any amount you specify. 
+
+\G{png.d/mmovevariable.png}
+
+The \f{Move} command is executed as follows;
+
+\n \f{Select} the object(s) to be moved.
+
+\lcont{\u000}
+
+\n \e{Shift+Right-Click} to raise the Move/Rotate menu. 
+
+\lcont{\u000
+
+Any amount of precise transalation may be entered by \e{Left-Click}ing the \f{Enter Move...} menu item then entering a desired amount of translation in X and Y in the dialog window that appears.
+
+\u000
+
+\G{png.d/dmovetranslate.png}
+
+\u000
+
+}   
+
 \rule
 
 
@@ -678,10 +868,15 @@ Click the \f{Move Description} button to activate the \f{Move Description} comma
 
 This operation can also be invoked by \e{Ctrl+Left+Drag} when in Select mode (\K{cmdSelect}).
 
-\e{Shift+Right-Click} (\K{cmdAcclKeys}) can be used to toggle display of individual Curved Track, Helix or Turnout Labels.
+\e{Shift+Right-Click} (\K{cmdAcclKeys}) can be used to toggle display of individual Curved Track, Bezier Track, Cornu, Helix or Turnout Labels.
 
 \rule
 
+\S{cmdPan} Pan/Zoom 
+
+\G{png.d/pan.png}
+
+This command is used to move or resize the viewport using the mouse or keyboard. \e{Left+Drag} Pans the viewport up and down, left and right keping it within the boundaries of the layout. \e{Right+Drag} selects an area of the screen to zoom into. The \f{"0"}- key resets the display to the origin but leaves the zoom as is. Keys between \f{1} and \f{9} set the zoom to that zoom level. The \f{"e"} - key resets the origin to zero and the zooms to show the whole layout. 
 
 \S{cmdProfile} Profile
 
@@ -799,7 +994,7 @@ Rotate An Object Using the Mouse
 
 \lcont{\u000}
 
-\n Visualize an axis point on the object that's to be rotated then place the mouse pointer over that point.
+\n Visualize an axis point on the object that's to be rotated then place the mouse pointer over that point. If the track is a turntable, the point will be snapped to the turntable center if the mouse is within a quarter of the radius length of it.
 
 \lcont{\u000}
 
@@ -828,7 +1023,11 @@ Rotation can also be achieved through use of one of these alternate methods;
 
 Rotate An Object Using Fixed or Specified Degree's of Rotation
 
-A pop-up menu with additional menu items allows you to \f{Rotate} the selected object(s) through various predefined angles or through any angle you specify. The \f{Rotate} command is executed as follows;
+A pop-up menu with additional menu items allows you to \f{Rotate} the selected object(s) through various predefined angles or through any angle you specify. 
+
+\G{png.d/mrotatemove.png}
+
+The \f{Rotate} command is executed as follows;
 
 \n \f{Select} the object(s) to be rotated.
 
@@ -838,24 +1037,34 @@ A pop-up menu with additional menu items allows you to \f{Rotate} the selected o
 
 \lcont{\u000}
 
-\n With the mouse pointer hovering over the object to be rotated, \e{Shift+Right-Click} to raise the Rotate menu then select the desired degree and direction of rotation from the list of predefined angles (180\u00B0, 90\u00B0 CW, 45\u00B0 CW, 30\u00B0 CW, 15\u00B0 CW, 15\u00B0 CCW, 30\u00B0 CCW, 45\u00B0 CCW, 90\u00B0 CCW). 
-
-\lcont{
+\n With the mouse pointer hovering over the point about which the object(s) are to be rotated, \e{Shift+Right-Click} to raise the Rotate menu then select the desired degree and direction of rotation from the list of predefined angles (180\u00B0, 90\u00B0 CW, 45\u00B0 CW, 30\u00B0 CW, 15\u00B0 CW, 15\u00B0 CCW, 30\u00B0 CCW, 45\u00B0 CCW, 90\u00B0 CCW). 
 
-\u000
+\lcont{\u000}
 
 \G{png.d/mrotatefixed.png}
 
-\u000
+\u000 
+
+\rule
+
+Alternately, any angle may be entered by \e{Left-Click}ing the \f{Enter Angle...} menu item 
+
+\n \f{Select} the object(s) to be rotated.
+
+\lcont{\u000}
+
+\n With the mouse pointer hovering over the point about which the object(s) are to be rotated, \e{Shift+Right-Click} to raise the Rotate menu and then select the \e{Enter Angle...} option.
+
+\lcont{\u000}
+
+\G{png.d/mrotatevariable.png}
 
-Alternately, any angle may be entered by \e{Left-Click}ing the \f{Enter Angle...} menu item then entering a desired angle in the Rotate dialog window that appears.
+And then entering a desired angle in the Rotate dialog window that appears.
 
 \G{png.d/drotateangle.png}
 
 \u000
 
-}
-
 Rotation can also be achieved through use of one of these alternate methods;
 
 \u000
@@ -883,7 +1092,7 @@ A pop-up menu with additional menu items allows you to \f{Align} the selected ob
 
 \lcont{\u000}
 
-\n With the mouse pointer hovering over the object to be rotated, \e{Shift+Right-Click} to raise the Rotate menu then select \f{Align}.
+\n With the mouse pointer hovering over the point about which the object(s) are to be rotated, \e{Shift+Right-Click} to raise the Rotate menu then select \f{Align}.
 
 \lcont{
 
@@ -1039,7 +1248,7 @@ For detail about;
 
 \u000
 
-\dd Dividing a section of track into two connected pieces see \K{splitDivide}.
+\dd Dividing a section of flex track into two connected pieces or trimming a turnout see \K{splitDivide}.
 
 \u000
 
@@ -1056,7 +1265,7 @@ Disconnecting a joint between two pieces of connected track;
 
 \lcont{\u000} 
 
-\n Place the mouse pointer over the joint between the two track endpoints then \e{Left-Click}.
+\n Place the mouse pointer right over the joint between the two track endpoints then \e{Left-Click}.
 
 \lcont{\u000}
 
@@ -1091,7 +1300,7 @@ For detail about;
 
 \S2{splitDivide} Divide Track
 
-Dividing a section of track into two connected pieces;
+Dividing a section of flex track into two connected pieces;
 
 \n Click the \f{Split} button (\G{png.d/bsplit.png}) to activate the \f{Split} command.
 
@@ -1164,7 +1373,7 @@ The \f{Split} command can be used to add block gaps (\K{generalTerms}) at the po
 
 \u000
 
-After executing the \f{Split} command use the \e{Shift+Right-Click} command to display one of two pop-up menus which can be used to add, change or remove \e{block gaps} for the selected endpoint.
+After starting the \f{Split} command use the \e{Shift+Right-Click} over a joint to display one of two pop-up menus which can be used to add, change or remove \e{block gaps} for the selected endpoint.
 
 \dd \G{png.d/msplitblock.png}