Initial import of xtrkcad version 1:4.0.2-2

1 files changed, 413 insertions, 0 deletions

diff --git a/app/doc/optionm.but b/app/doc/optionm.but
new file mode 100644
index 0000000..e6d49e0
--- /dev/null
+++ b/app/doc/optionm.but
@@ -0,0 +1,413 @@
+\# Notes:
+\#
+\# The "\u000" command is used to format the output. The command causes a blank line to appear between "bulleted" or "described" items.
+\#
+\# The "\u00B0" command gives proper format to the degree sign.
+
+\H{optionM}\i{Options Menu}
+
+\G{png.d/moptions.png}
+
+The \f{Options Menu} shows commands to change configuration options.
+
+\dd \f{Colors} - Displays the Colors (\K{cmdRgbcolor}) dialog.
+
+\u000
+
+\dd \f{Command} - Displays the Command Options (\K{cmdCmdopt}) dialog.
+
+\u000
+
+\dd \f{Display} - Displays the Display (\K{cmdDisplay}) dialog.
+
+\u000
+
+\dd \f{Easement} - Displays the easement (\K{cmdEasement}) dialog which controls how easements (spiral transition curves) are used to join tracks.
+
+\u000
+
+\dd \f{Fonts} - Displays the font selection (\K{fontSelW}) dialog which selects the font used by the text (\K{cmdText}) command.  This command is only available on UNIX based systems. 
+
+\u000
+
+\dd \f{Layout} - Displays the layout (\K{cmdLayout}) dialog.
+
+\u000
+
+\dd \f{Preferences} - Displays the Preferences (\K{cmdPref}) dialog.
+
+\u000
+
+\dd \f{Sticky} - Displays the Sticky Commands (\K{cmdSticky}) dialog.
+
+\rule
+
+
+\S{cmdRgbcolor} Colors Dialog
+
+The \f{Colors} dialog is invoked from the Options (\K{optionM}) menu
+
+\G{png.d/colorw.png}
+
+The \f{Colors} dialog controls the color that various objects are drawn.
+
+\dd \f{Border} - Sets color of Rulers, Room Boundaries and Table Edges.
+
+\u000
+
+\dd \f{Exception Track} - Sets color of \e{Exceptional Tracks} (\K{cmdLayout}). Those which exceed the specified grade or are have a radius smaller than the minimum set.
+
+\u000
+
+\dd \f{Marker} - Sets color of short lines drawn on the Ruler of the Main (\K{mainW}) window to indicate cursor position.
+
+\u000
+
+\dd \f{Normal Tracks} - Sets color of normal track.
+
+\u000
+
+\dd \f{Primary Axis} - Sets color of the large cross displayed when positioning the \f{Snap Grid} (\K{cmdGrid}) or the \f{Print Grid} (\K{cmdPrint}).
+
+\u000
+
+\dd \f{Profile Path} - color of the path when using the \f{Profile} (\K{cmdProfile}) command.
+
+\u000
+
+\dd \f{Secondary Axis} - Sets color of the large cross displayed when positioning the \f{Snap Grid} (\K{cmdGrid}) or the \f{Print Grid} (\K{cmdPrint}).
+
+\u000
+
+\dd \f{Selected Tracks} - Sets color of Selected track.
+
+\u000
+
+\dd \f{Snap Grid} - the Grid displayed by the \f{Snap Grid} (\K{cmdGrid}) dialog.
+
+\u000
+
+\dd \f{Track Ties} - color of ties (if drawn).
+
+\rule
+
+
+\S{cmdCmdopt} Command Option Dialog
+
+The \f{Command Option} dialog is invoked from the Options (\K{optionM}) menu
+
+\G{png.d/cmdopt.png}
+
+The \f{Command Option} dialog contains items which control the behavior of some commands.
+
+\dd \f{Draw Moving Tracks} - how to draw tracks during move and rotate operations. See  \K{cmdSelect} and \K{cmdMove} for additional detail.
+
+\u000
+
+\dd \f{Default Command} - selects the \f{Properties} (\K{cmdDescribe}) or \f{Select} (\K{cmdSelect}) as the default command which is invoked when any other command (if not \f{Sticky} (\K{cmdSticky})) is canceled or completed.
+
+\u000
+
+\dd \e{Right-Click} - will either display a pop-up menu of available commands or command-specific options depending on whether the \e{Shift} key is being held down or not.  This option allows you to choose which operation occurs.
+
+\rule
+
+
+\S{cmdDisplay} Display Dialog
+
+The \f{Display} dialog is invoked from the Options (\K{optionM}) menu
+
+\G{png.d/displayopt.png}
+
+The \f{Display} dialog contains items which control the display of objects on the Main window.
+
+\dd \f{Auto Pan} - if enabled, dragging near the edge of the Main Canvas (\K{mainW}) will cause the canvas to move to follow the mouse.
+
+\u000
+
+\dd \f{Car Labels} - controls the grouping and display of \f{Cars} on the \f{Hot Bar} (\K{cmdHotBar}) during the \f{Train} (\K{cmdTrain}) command.  This can be a combination of \f{Prototype}, \f{Manufacturer}, \f{Part Number} and \f{Item}.
+
+\u000
+
+\dd \f{Color Layers} - when set, tracks and/or non-tracks (lines, table edges and structures) are drawn with color of the layer (\K{cmdLayer}) they belong to.
+
+\u000
+
+\dd \f{Draw EndPts} - when to draw endpoints between connected track: never, only for turnouts or for all tracks.
+
+\u000
+
+\dd \f{Draw Ties} - how to draw ties under the rails when the drawing Scale is smaller than half of the \f{Two Rail Scale}.
+
+\u000
+
+\dd \f{Draw Centers} - enable or disable drawing of center markings (ie. crosshairs) for curved track.
+
+\u000
+
+\dd \f{Draw Tunnel} - how to draw hidden tracks (\K{cmdTunnel}), either not at all, as dashed lines or as normal solid lines (which might be faster).
+
+\u000
+
+\dd \f{Hide Trains On Hidden Track} - controls whether trains (\K{cmdTrain}) on invisible layers (\K{cmdLayer}) or hidden tracks (\K{cmdTunnel}) (if hidden tracks are not drawn) are displayed.
+
+\u000
+
+\dd \f{Hot Bar Labels} - controls the format of titles for objects on the \f{Hot Bar} (\K{cmdHotBar}).
+
+\u000
+
+\dd \f{Label Enable} - individual control over whether to display various types of labels.  You may want to turn some of these off if your layout is too cluttered.
+
+\lcont{
+
+\u000
+
+\b \e{Cars} - Reporting mark labels on cars.
+
+\b \e{EndPt Elevations} - Elevation markers attached to endpoints.
+
+\b \e{Lengths} - Length of flex-track attached to ends of turnouts.
+
+\b \e{Track Descriptions} - Title of each turnout and sectional track.
+
+\b \e{Track Elevations} - Computed elevations at the center of each track.
+
+}
+
+\u000
+
+\dd \f{Label Font Size} - controls font size for Labels on layout.
+
+\u000
+
+\dd \f{Layout Labels} - controls the format of titles for turnouts and structures displayed on the Layout.
+
+\u000
+
+\dd \f{Label Scale} - draw labels only when the drawing Scale is smaller or equal to this value.
+
+\u000
+
+\dd \f{List Labels} - controls the format of titles for turnouts and structures displayed in lists (such as the \f{Parts List} (\K{cmdEnum})).
+
+\u000
+
+\dd \f{Live Map} - if checked then the Main Window (\K{mainW}) will be updated as you drag on the \f{Map Window} (\K{cmdMap}).  Note that this can be slow.
+
+\u000
+
+\dd \f{Map Scale} - scale of the Map (\K{cmdMap}) window.  Increase this value to make the \f{Map} window smaller when working with large layouts.  \f{Note:} you cannot make the \f{Map} window larger than the screen.
+
+\u000
+
+\dd \f{Train Update Delay} - number of milliseconds between updates in the \f{Train Simulation} (\K{cmdTrain}) mode.  A lower value will generate a smoother display but reduces system responsiveness.
+
+\u000
+
+\dd \f{Two Rail Scale} - draw tracks using two lines when the drawing Scale is smaller than this value.
+
+\rule
+
+
+\S{cmdEasement} \i{Easements}
+
+Easements are special sections of gradually curving track used to connect straight and curved tracks (or two curved tracks). Easements reduce the effects of sudden changes in track curves which can cause jerky motion and derailments.
+
+Easements can be created every time you \f{Join} (\K{cmdJoin}) tracks, \f{Extend} (\K{extendTrack}) a track or create a \f{Tangent} (\K{createTangent}) track.
+
+When using easements, an error message will be generated if tracks have a radius that is too small or are too short for the transition curve.
+
+The \f{Easement} dialog is invoked from the Options (\K{optionM}) menu.
+
+\dd \G{png.d/easew.png}
+
+\u000
+
+\dd \f{Value} - allows fine tuning of the easement parameters (restricted to values >= 0.5).
+
+\u000
+
+\dd \f{R} - minimum radius of the curved track.
+
+\u000
+
+\dd \f{X} - offset between a straight and curved track.
+
+\u000
+
+\dd \f{L} - length of the transition track.
+
+\u000
+
+\dd Radio button group with \f{None}, \f{Sharp}, \f{Normal} and \f{Broad}. Corresponding \f{Value}s for these buttons are 0, 0.5, 1.0 and 2.0. Select \f{None} to turn easements off.
+
+The values \f{R}, \f{X} and \f{L} are read-only.
+
+These values indicate the worst case of joining a straight track with a curve of radius \f{R}. The two tracks are separated by the offset \f{X} while the easement curve extends for \f{L/2} inches or centimeters to each side of the endpoints.
+
+The formula used to draw easements is:
+
+\c          x = l * l * l / (6 * R * L)
+\e                               b   b
+\c          r = L * R/l
+\e              b   b
+
+where
+
+\b \f{l} is the distance along the tangent to the easement.
+
+\b \f{R} is the final radius of the easement.
+
+\b \f{L} is the total length of the easement along the tangent.
+
+\b \f{x} is the offset from the tangent at \f{l}.
+
+\b \f{r} is the radius of easement curve at \f{l}.
+
+The Easement Button (\G{png.d/beasement.png}) on the Main Window (\K{mainW}) changes its label to indicate the current easement value.
+
+The following diagrams illustrates the \f{R}, \f{X} and \f{L} values and the resulting easement curve.
+
+\G{png.d/easeex1.png}
+
+\G{png.d/easeex2.png}
+
+If curves with a radius larger than \f{R} or two curves (that bend in the same direction) are being connecting then the easement curve will be shorter and the offset smaller.  If the computed offset is small then no easement is generated.  
+
+A curved track that bends in one direction and then bends in the opposite direction is an \e{S-curve}.  This will generate the worst case easement which is two easement curves placed end to end.
+
+Refer to instruction in \k{EasementsSectional} when using sectional track.
+
+\rule
+
+
+\S2{EasementsSectional} \i{Easements and Sectional Track}
+
+Easements require the possibility of creating track with arbitrary radii. Therefore easements are not possible if sectional track is used. It is best to turn \f{Easements} off when using sectional track.
+
+\rule
+
+
+\S{fontSelW} Font Selection
+
+The font selection dialog allows selection of the font used by the text (\K{cmdText}) command.  This command is valid only on UNIX based systems.
+
+\G{png.d/fonts.png}
+
+\rule
+
+
+\S{cmdLayout} Layout Dialog
+
+The \f{Layout Options} dialog, displayed by the Options (\K{optionM}) menu, contains items controlling the current layout.
+
+\dd \G{png.d/layout.png}
+
+\u000
+
+\dd \f{Gauge} - Drop down menu used to select track gauge.
+
+\u000
+
+\dd \f{Height} - Height of layout drawing which, depending on the \f{Unit} setting (English or Metric) established in the \f{Preferences} dialog (\K{cmdPref}), is measured in inches or centimeters.
+
+\u000
+
+\dd \f{Room Width} - Width of layout drawing which, depending on the \f{Unit} setting (English or Metric) established in the \f{Preferences} dialog (\K{cmdPref}), is measured in inches or centimeters.
+
+\u000
+
+\dd \f{Scale} - Drop down menu used to select track scale.
+
+\u000
+
+\dd \f{Title} - Two lines that can be used to enter title and subtitle descriptions for the layout. Information entered in these fields will be shown on any printout of your layout design.
+
+\u000
+
+\dd \f{Maximum Track Grade} - Specifies maximum track elevation expressed as a percent (%). Tracks with a larger elevation are considered exceptional and drawn in the exception (\K{cmdRgbcolor}) color.
+
+\u000
+
+\dd \f{Minimum Track Radius} - Specifies minimum track radius (in inches or centimeters). Curved tracks with a smaller radius are considered exceptional and drawn in the exception (\K{cmdRgbcolor}) color.
+
+\rule
+
+
+\S{cmdPref} Preferences Dialog
+
+This dialog controls some parameters which likely will not be changed frequently.
+
+\dd \G{png.d/pref.png}
+
+\u000
+
+\dd \f{Angles} - controls the angle system. \f{Polar}: 0\u00B0 is up and angles are measured clockwise, or \f{Cartesian}: 0\u00B0 is to the right and angles are measured counter-clockwise.
+
+\u000
+
+\dd \f{Balloon Help} - disables the display of \f{Balloon Help} (\K{windowTerms}) which usually is shown when the cursor is placed over a control.
+
+\u000
+
+\dd \f{Check Point} - specifies the Check Point frequency; the number of modifications made to the layout since the last save. The layout is automatically saved to the Check Point file (\K{workDir}) when the Check Point frequency is reached. Setting this value to 0 disables use of the Checkpoint file.
+
+\u000
+
+\dd \f{Connection Angle} - as below for Connection Distance for the angle between endpoints.
+
+\u000
+
+\dd \f{Connection Distance} - the maximum distance between endpoints that can be connected.  This affects the \f{Join} (\K{cmdJoin}) command and auto-connection during \f{Parallel} (\K{cmdParallel}) commands and placing \f{Turnouts} (\K{cmdHotBar}).  The default value for this field is 0.100 inches or 0.254 CM. Changing this value is not recommended.
+
+\u000
+
+\dd \f{Drag Distance} - controls how far you can move the cursor (in pixels) before \e{XTrackCAD} considers the action to be a drag instead of a click.
+
+\u000
+
+\dd \f{Drag Timeout} - controls how long you can hold a mouse button down (in milliseconds) before \e{XTrackCAD} considers the action to be a drag instead of a click.
+
+\u000
+
+\dd \f{Length Format} - controls how lengths are displayed.  Combinations of feet and inches (or meters, centimeters and millimeters) with support for decimal or fractional measures. \f{Note:} lengths can be entered in any format and are converted on entry.
+
+\u000
+
+\dd \f{Max Coupling Speed} - trains (\K{cmdTrain}) moving faster than this speed will crash when running into other trains or hitting the end of a track or an open turnout.  Crashed trains must be manually moved back onto the track.
+
+\u000
+
+\dd \f{Min Grid Spacing} - minimum distance between \f{Grid} (\K{cmdGrid}) lines (in pixels).  If the grid lines are closer then drawing them is suppressed.
+
+\u000
+
+\dd \f{Min Track Length} - specifies the minimum length of a track.  Shorter tracks will not be created.
+
+\u000
+
+\dd \f{On Program Startup} - if set to \q{Load Last Layout}, \e{XTrackCAD} will automatically re-open the layout file that was open when \e{XTrackCAD} last closed. Selecting \q{Start New Layout} opens a blank layout canvas.
+
+\u000
+
+\dd \f{Turntable Angle} - minimum angle between adjacent tracks connected to a \f{Turntable} (\K{cmdTurntable}).
+
+\u000
+
+\dd \f{Units} - choose between English (inches) or Metric (centimeters) measurements.
+
+\rule
+
+
+\S{cmdSticky} Sticky Dialog
+
+By default, when commands complete, the defined \f{Default Command} (\K{cmdCmdopt}) becomes active.  If a command is \f{sticky}, the defined \f{Default Command} is ignored and the current command remains active after completion.
+
+The \f{Sticky} dialog controls which commands remain active after completion.
+
+\G{png.d/sticky.png}
+
+Selecting a command makes it \f{sticky}. Un-selecting a command causes the defined \f{Default Command} to become active after command completion.
+
+\rule