path: root/app/doc/intro.but.in

\# Notes:
\#
\# The "\u000" command is used to format the output. The command causes a blank line to appear between "bulleted" or "described" items.
\#


\# Identify XTrackCAD Version, Microsoft Windows software installation package name and Copyright information

\define{XTCVer} Version @XTRKCAD_VERSION@

\define{XTCWinPack} xtrkcad-setup-@XTRKCAD_VERSION@.exe

\define{XTCRPMPack} xtrkcad-setup-@XTRKCAD_VERSION@.i386.rpm

\define{XTCStgzPack} xtrkcad-setup-@XTRKCAD_VERSION@.i386.sh

\define{XTCCopyRight} Copyright 2003, Sillub Technology and
Copyright 2007, Bob Blackwell and Martin Fischer and
Copyright 2020, Martin Fischer, Adam Richards and Dave Bullis


\# Index Groupings

\IM{Bench-work}{Bench-work Notes} Bench-work

\IM{Directories Overview}{Install Directory}{Working Directory} Directories

\IM{Easements}{Easements and Sectional Track} Easements

\IM{Export}{Export to Bitmap}{Export to DXF} Export

\IM{Window Terms}{XTrackCAD Terms} Glossary

\IM{Install directory}{Linux Installation}{Microsoft Windows Installation} Installation

\IM{Copying and Distribution}{GNU General Public License} License

\IM{Add Menu}{File Menu}{Edit Menu}{View Menu}{Change Menu}{Draw Menu}{Manage Menu}{Options Menu} Menus

\IM{Entering Values}{Keyboard Shortcuts}{Main Window Overview}{Map Window}{Mouse Actions}{Shortcut Keys}{Typographic Conventions} Navigation

\IM{printDesignToRoadbed}{Linux}{Microsoft Windows}{Printing} Printing

\IM{Additional Shortcut Keys}{Hot Bar}{Keyboard Shortcuts}{Main Drawing Canvas}{Mouse Actions}{Shortcut Keys} Shortcut Keys

\IM{Created by Turnout Command}{Easements and Sectional Track} Sectional Track

\# >>>>>>>>>> Manual Begin's Here <<<<<<<<<<

\title \e{XTrackCAD} User's Manual

\G{png.d/xtrkcad_logo.gif}

\e{\XTCVer}

\copyright \XTCCopyRight

\rule

\C{index} Introduction To \e{XTrackCAD}

\cfg{html-local-head}{<meta name="AppleTitle" content="org.xtrkcad.help" />}

\e{XTrackCAD} is a CAD (computer-aided design) program for designing Model Railroad layouts. \e{XTrackCAD} supports any scale, has libraries of popular brands of turnouts and sectional track (plus you add your own easily), can automatically use spiral transition curves when joining track and has extensive on-line help and demonstrations. \e{XTrackCAD} lets you manipulate track much like you would with actual flex-track to modify, extend and join tracks and turnouts. Additional features include tunnels, 'post-it' notes, on-screen ruler, parts list, 99 drawing layers, undo/redo commands, bench-work, 'Print to Bitmap', elevations, train simulation and car inventory.

Using it, you can

\b Design layouts in any scale and gauge,

\u000

\b Use predefined libraries for many popular brands of turnouts to help you get started easily,

\u000

\b Add your own favorite components,

\u000

\b Manipulate track much like you would with actual flex-track to modify, extend and join tracks and turnouts,

\u000

\b Automatically generated Cornu \e{transition curves} (easements) whenever the track radius changes.

\u000

\b Test your design by running trains, including picking them up and moving them with the mouse.

\u000

\b Trace tracks and other objects over a background image of a real-world location map, a scanned trackplan, or other image.

\u000

\b Print the design in a scale of your choice.  When printed in 1:1 scale the printout can be used as a template for laying the track to build your dream layout.

\u000

New users should run the demonstrations (via the \f{Help>Demos} menu) to get an overview of the many features of the program.  A number of example layout designs are also available.

Be sure to visit the project web page for latest news and updates: \W{http://www.xtrkcad.org/}{\e{XTrackCAD} Fork Website}

\rule


\H{whyXTrackCAD} Why Choose \e{XTrackCAD}

\f{Why Choose XTrackCAD}

\f{Easy to use}

 \e{XTrackCAD} was designed to operate in a similar way to pencil and paper: You can draw tracks by dragging the mouse, you select and place turnout "templates" anywhere on existing tracks, and you can use fixed radii for initial design.

But extra capabilities have been added that give more power by using FlexTracks (Cornu) you have tracks that automatically redraw as you drag turnouts around, creating smooth curves, you can zoom in and out, and of course, undo and deleting tracks are easier!

You don't have to be an expert CAD user to make the most of \e{XTrackCAD} but the program will ensure that dimensions, radii and angles are accurate.

You don't have to specify line lengths or angles and just draw. But if you want to be more precise, you can enter precise dimensions both in real-world and scale sizes.

\e{XTrackCAD} is a specialized CAD for railway modelling, it deals with tracks as tracks, not as line segments. Tracks are connected correctly to each other and with endpoints of turnouts and other components.

As you zoom in, the two rails are drawn and then ties are added.

\f{Free}

Thanks to the generosity of Dave Bullis, who wrote the progam, and the active help of open-source volunteers, XTrackCAD is free to own and use. You can even take up the cudgels and help!

\f{Available Help}

On-line demonstrations show the actual operation of many of the program's features. Extensive help is available for all commands and operations.  There are communities of users and developers who can answer quaestions.

\f{Packed with features}

\e{XTrackCAD} is designed from the ground up to be a complete tool for many aspects of Model Railroad layout design.

\dt \e{Active UI Prompting}

\dd As the mouse moves over the layout objects, a set of different anchors are shown to indicate what is possible in each command with each modifier key if clicked or double clicked at that location.

\u000

\dt \e{Train Simulation and Car Inventory}

\dd Any number of Cars and Locomotives can be placed on your layout to check clearances, siding capacities and track layout. Trains can be animated to simulate operations and switching on your layout.

\u000

\dd The Car Inventory dialog records your cars and locomotives and these can be exported and imported from spreadsheets.

\u000

\dt \e{Track Manipulation}

\dd Track segments can be lengthened or shortened by simple click and drag. Tangents to a curve are created by dragging away from the curve. Tracks are extended by dragging from an Endpoint, creating new straight or curved segments. New tracks can be snapped into place or precisely placed and then Joined.

\u000

\dd Track circles are especially handy for determining overall designs and seeing what will fit in a given area.

\u000

\dd The Cornu flextrack features create dynamically variable tracks that optimise the curvature of tracks to ensure a protypical appearance. They alter as the other tracks are moved just as flextrack will in the 12 inches to the foot world!

\u000

\dd The Parallel command easily creates new straight or curved tracks, laying out yards and sidings in a few easy steps. Accurate platforms can be created with the Parallel Lines command followed by the Join Lines command.

\u000

\dd The Join command links any two tracks (Straights, Curves, Turnouts or Turntables) with accurate aligned connecting track segments which can be easements including Cornu easements. The connected tracks are trimmed or extended as required.

\u000

\dd The Helix Track command computes the number of turns, radius, grade and vertical separation based on your criteria.

\u000

\dd Turntables can be constructed with any radius and can either have fixed or dynamic bay tracks

\u000

\dt \e{Turnout Select and Placement}

\dd The Turnout Hot Bar contains a scrolling list of Turnouts, Sectional Tracks and Structures available in the current Scale. Simply click on one and click again drop it onto the layout.

\u000

\dd As Turnouts are dragged over existing tracks they are automatically aligned. \e{XTrackCAD} searches for any other tracks that align with each of the Turnout's Endpoints, and shows you the number of connections that will be made and the maximum offset as you position the Turnout.
Just adjust the Turnout's position to minimize the offset to ensure the best fit.

\u000

\dd When a turnout is placed, each Endpoint is examined to see if it aligned to an existing track. If so, the track is split to create a perfect connection to the turnout. Placing Turnouts is a 'snap'.

\u000

\dt \e{Layers}

\dd Layers are an important feature for manageing the design for layouts of any complexity. Use one layer for the main-line and others for staging tracks, Bench-work or scenery. Multilevel designs can have groups of layers for each level.

\u000

\dd \e{XTrackCAD} allows up to 99 layers layers can have their own button to control visibility. Each layer can have a name which is displayed as the balloon help for the layer button.

\u000

\dd Modular Layout assembly is supported with Modular Layers which ensure thier contents are moved as a set.

\u000

\dd Tracks and other objects can be colored according to which layer they are in. Also, each layer can be frozen to prevent accidental changes to parts of the layout that are finalized.

\u000

\dt \e{Elevations and Profile}

\dd Elevations are one of the most powerful features of \e{XTrackCAD} they are dynamically recalulated as the layout changes.

\u000

\dd Traditional layout designs (such as published in magazines) show elevations at selected spots on the layout. They may also show grades between elevations. These can be input into XtrkCAD.

\u000

\dd \e{XTrackCAD} lets you define the elevation of any Endpoint on the layout. You can also have \e{XTrackCAD} automatically compute the elevation and grade between defined elevation points. You can define the elevation at the bottom and top of a sloped track, then have \e{XTrackCAD} compute the elevation at each riser position between.

\u000

\dd Once you have defined a few elevations, you can display the Elevation Profile for the layout along a path of connected track segments. The Profile display shows the length of the track, the elevation of each defined elevation point and the grades between them. You can even adjust the elevations directly on the Profile display.

\u000

\dt \e{Easements (Cornu Transition Curves)}

\dd 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 derailments. They also look great!

\u000

\dd \e{XTrackCAD} can use Easements anytime the radius of the track changes. The Modify and Join commands will automatically insert Easement Track segments whenever needed. Each Easement is computed based on the radius of the neighboring tracks. You don't even have to think about it!

\u000

\dt \e{Flexible and Powerful Printing}

\dd Printing is an important part of a layout design program, and \e{XTrackCAD} has a flexible Print command to get your design onto the layout.

\u000

\dd Printing is used for many purposes:

\lcont{

\b A snapshot of the whole layout.

\b Detailed closeups to examine areas of complicated track work.

\b Full 1:1 for direct transfer to the layout.

}

\u000

\dd The Print command lets you scale the printout from a one page overall view (with the handy Snap-Shot button) right up to full size 1:1.

\u000

\dd Multiple page printouts are easy to do. A gird representing each page is drawn over the layout and you can click on the pages you want to print. The gird can be moved and rotated to any position so the orientation of the printout matches your layout. Pages can be printed in Portrait or Landscape format.

\u000

\dd At 1:1, registration marks can be printed every 3" (or 10cm) to help align different sets of printouts. Also, the roadbed outline can be drawn at a user-specified width to assist cutting the roadbed from sheet material.

\u000

\dt \e{Turnout and Structure Creation}

\dd \e{XTrackCAD} comes with Turnout, Sectional Track and Structure Parameter Files for many brands of tracks and accessories. However, your brand may not supplied. The Turnout Designer dialogs and the Group command make it easy to add your own custom definitions.

\u000

\dd The Turnout Editor has separate screens for designing Turnouts (Regular, Curved, Wye and 3-way), Crossings, Slip-switch, Crossovers and Sectional Track. In each dialog a few measurements are required to create a new definition. Full size printouts can be made directly from the dialog to check your design.

\u000

\dd The Group command can create Structure definitions from selected tracks, lines and shapes. You can make structures as simple as a rectangle or highly detailed. You can also modify existing designs to add details or make adjustments.

\u000

\dt \e{Lines, Shapes, Table Edges, Text and Notes}

\dd Layout designs are more than track!

\u000

\dd The \e{XTrackCAD} Draw command is used to draw lines (straight, curved and circles) and shapes (filled boxes, circles, polylines and polygons). These can be different colors and lines can have different widths. The Polylines and Polygons can have curved sides. These are useful for drawing scenic features (rivers, bridges, mountains).

\u000

\dd You can add Bench-work and dimension lines too.

\u000

\dd Special types of lines are drawn by the Table Edge command are used to represent the boundary at the edge of the layout.

\u000

\dd Text can be added to the layout.

\u000

\dd Notes can be attached to particular spots on the layout. When selected they can display special information about that part of the layout, such as prototype features, construction details or operation notes.  This includes URL links to files on the Internet.

\u000

\dt \e{Parts and Price Lists}

\dd The Parts List command generates a list of the number of the different types of Turnouts, Sectional Track and Structures selected on the layout. You can select everything or just the areas you are working on. As well, the total length of flex-track (for each track scale/gauge used on the layout) is listed.

\u000

\dd You can enter the price of each type of Turnout, Sectional Track and Structure, plus the length and price of flex-track. \e{XTrackCAD} will compute the price of each types and the grand total. The total number of flex-track sections is also listed.

\u000

\dt \e{Support for Sectional Track}

\dd Numerous Sectional Track Parameter Files are included with \e{XTrackCAD} (Atlas, Marklin, Peco, ...). The Hot Bar allows easy selection.

\u000

\dd The automatic alignment feature of Turnout and Sectional Track placements makes track pieces just 'snap' together.

\u000

\dd The Connect Track command adjusts Sectional Track to smooth out the slight gaps that can arise when working with Sectional Track.

\u000

Refer to \K{keyFeatures} and \K{addFeatures} for a listing of \e{XTrackCAD} features.


\H{keyFeatures} Key \e{XTrackCAD} Features

\b Annotate with text and notes

\u000

\b Automatic easement calculation

\u000

\b Create Custom Designed Turnouts and Structures

\u000

\b Create parallel straight and curved tracks

\u000

\b Delete objects

\u000

\b Describe objects

\u000

\b Draw lines, arcs, polylines and polygons and filled polygons or circular shapes (for showing river edges etc.)

\u000

\b Draw table edges, Bench-work and dimension lines

\u000

\b Elevations, grades and profiles

\u000

\b Extend (or shrink) a segment by dragging its Endpoint

\u000

\b Extend a segment with a curve (or straight)

\u000

\b Generate parts list for all or selected areas of the layout

\u000

\b Hand-laid Turnouts

\u000

\b Helix track

\u000

\b Hot Bar for Turnout and Structure selection

\u000

\b Join any two tracks

\u000

\b Move and rotate any group of objects

\u000

\b Ninety-nine drawing Layers

\u000

\b On-line demonstrations, extensive help, tips and error message explanations

\u000

\b On-screen ruler for measurements

\u000

\b Panning and zooming via a map window and also in Pan/Zoom Mode

\u000

\b Price lists can be entered to allow the layout to be priced

\u000

\b Printing in any scale (up to 1:1) at any position and angle

\u000

\b Straight and curved flex-track segments

\u000

\b Supports any scale

\u000

\b Track circles and tangent tracks

\u000

\b Train Simulation

\u000

\b Tunnels (hidden tracks)

\u000

\b Turnouts, crossings (and sectional track such as Atlas Snap-track)

\u000

\b Turntables (user defined diameter)

\u000

\b Undo the last ten commands

\u000

\b Zoom in and zoom out of the drawing area

\rule


\H{addFeatures} Additional \e{XTrackCAD} Features

\e{XTrackCAD} has many other carefully selected features:

\b Sections of track can be hidden, which can be drawn as dashed lines, or completely hidden. A Tunnel Portal is drawn when a hidden track connects with normal track.

\u000

\b Sections of track can be tagged as bridge tracks which draws a bridge parapet on each side.

\u000

\b Drawing Turntable stall tracks is easy, just drag from the Turntable with the Modify command. The minimum angle between tracks can be set to ensure accurate, evenly spaced tracks.

\u000

\b Connections to non-visible layers are marked to an arrow head to show you the track continues on another layer.

\u000

\b The Group command can be used to decorate custom designed Turnouts and Sectional Track with details to indicate switch machines, ground throws and power connections.

\u000

\b Custom designed Turnouts can be modified, renamed or deleted with the Custom Management dialog.

\u000

\b Flex-track connected to Turnouts is labeled with the total length to aid cutting flex-track to length.

\u000

\b An on-screen ruler can be user to measure arbitrary distances.

\u000

\b At 1:1 drawing (and printing) scale the track center line is drawn to make it easy to position roadbed and track.

\u000

\b The balloon help for the Undo and Redo buttons shows the command that would be Undone or Redone.

\u000

\b The Snap Grid can positioned at any origin and any angle. It can also be printed to help when transferring coordinates to the layout.

\u000

\b The Map window is used to position the Main window on the layout. It can also be used to change the drawing scale.

\u000

\b You can rescale and flip objects, trim turnouts and create block gaps.

\u000

\rule

\H{aboutmanual} About This Manual

\i\f{Typographic Conventions}

Throughout this manual the following typographic conventions are used to make finding information easier:

\dd \f{Bold} - Shows menu, file or dialog item titles.

\u000

\dd \c{Mono-spaced} - Shows commands or text entries by user.  On entry fields the spelling given has to be followed exactly.

\u000

\dd \e{Italic} - Marks a new expression, usually followed by a short description

\u000

\dd \c{Capital Key} - Usually used in a sequence of key strokes or in combination with \e{Shift, Alt or Ctrl} key.

\u000

\dd \c{Key+Key} - Combination of keys, e.g., \c{Ctrl+S}

\u000

\dd \c{Key, Key, Key} - Sequence of key strokes, e.g., \c{Alt, F, S}

\u000

\dd \f{Selection>Selection} - Sequence of selections from menu, e.g., \f{File>Save}

\rule


\H{installSoftware} Installation

\e{XTrackCAD} is designed to operate under Linux, Apple MacOS or Microsoft Windows. Information within this section of the manual pertains to installation of the application in either of these environments.

\rule

\S{MSWinInstall} \i{Microsoft Windows Installation}

\e{XTrackCAD} is shipped as a self-installing self-expanding program (executable).

\n Using Windows Explorer, locate the directory in which you downloaded or copied your new version of \e{XTrackCAD}.

\lcont{\u000}

\n Start the installation program by double clicking on the \f{\XTCWinPack} file icon.

\lcont{\u000}

\n Follow the steps in the installation program.

\lcont{\u000}

\n The installation lets you define the directory in which \e{XTrackCAD} is installed.  The directory is created automatically if it doesn't already exist.

\lcont{\u000}

\n A program folder named \c{XTrkCad} will be created during the installation process.  The folder contains the program, documentation, parameter and example files.

\rule

\S{OSXInstall} \i{OSX Installation} \i{Mac Installation}

\e{XTrackCAD} for OSX is shipped as a package containing an application.

\n Start the installation by opening the package and dragging the contained application into the \e{Applications} folder using the shortcut in the package.
The application includes the program, documentation, parameter and example files within it.

\lcont{\u000}

\n To run on Apple MacOS, the \e{XQuartz} package must first have been installed - see \W{http://www.xquartz.org}{http://www.xquartz.org}. XQuartz will need to be upgraded after each OS version upgrade.

\lcont{\u000}

\n \i{OSX Run Security} When the application is first run, it will need to be authorized by OSX. There will be a OSX prompt that asks if it should be opened. And then it will still fail to run.
After opening it for the first time, go to \e{System Preferences>Security & Privacy} and you will see that the app is named as having been blocked. Hit the \e{Run Anyway} button and the program should start.
This sequence may be necessary after each OS upgrade.

\n On Mac OS Catalina, the program will need to be started by right-clicking it and selecting \f{Open}.

\rule

\S{LinuxInstall} \i{Linux Installation}

\e{XTrackCAD} for LINUX is shipped as a self-extracting archive (executable).

\n Installing from the self-extracting archive.

\lcont{

\dd After downloading open a command line then

\dd \c{./\XTCStgzPack --prefix=/usr/local --exclude-subdir}

\dd This will install the executable in /usr/local/bin. A directory named \c{xtrkcad} will be created in
/usr/local/share and all files will be unpacked into it.

}

If you install \e{XTrackCAD} into another directory, set the \c{XTRKCADLIB} environment variable to point to that directory.

\rule

\H{startSoftware} \i{Start the Program}

The \e{XTrackCAD} executable is named xtrkcad.exe on Windows and xtrkcad on Linux and OSX.

It is usually started by clicking on its icon, or right-click and \f{Open} in OSX Catalina, but there are command line options as well.

\f{Command Line}

On Windows:

\c xtrkcad [/c config] [/v] [/l logfile] [/d logcontrol] layoutfile

On Mac OSX:

\c cd /Applications
\c ./open xtrkcad --args [-c config] [-v] [-l logfile] [-d logcontrol] layoutfile

On Linux:

\c xtrkcad [-c config] [-v] [-l logfile] [-d logcontrol] layoutfile

\f{Command line parameters}

\dt \c{c config}

\dd configuration to use. This allows you to have several distinct configurations (eg.
parameter files, display options).

\u000

\dt \c{layoutfile}

\dd filename for the layout to load.
This parameter takes precedence over the option to resume with the last layout (\K{cmdPref}).

\f{Debugging Parameters}

The following parameters are for debugging purposes and are mainly of interest to the
developers.

\dt \c{v}

\dd verbose mode.

\u000

\dt \c{d logcontrol}

\dd specifies the amount of logging. The argument logcontrol has the format \c{logmodule[=level]}.
logmodule defines the functionality that should be logged, the optional level specifies the loglevel. Zero means no logging.
Defaults are no modules are logged and loglevel is 1 if omitted from logonctrol parameter.

\u000

\dt \c{l logfile}

\dd set logfile, only needed in conjunction with the debug option.

\dt \c{V}

\dd Display the xtrkcad version and exit(0).

\u000

\H{introQT} Quick Tour

\G{png.d/main.png}

When \e{XTrackCAD} starts, it displays the \f{Main} (\K{mainW}) and \f{Map} (\K{cmdMap}) windows.  The \f{Map} window is used to change the origin of the \f{Main} window when the entire layout cannot be displayed at one time.

\G{png.d/maintagged.png}

The Menu Bar across the top of the \f{Main} window contains standard Windows menus.  Some of these are particularly useful to the new user:

\b The \f{File>Exit} menu exits \e{XTrackCAD}.  You can also exit by selecting the System menu in the upper left corner of the Window.

\u000

\b The \f{File>Open} menu opens existing layout files and archives. When first installed, the default directory contains some example programs you can look at.

\u000

\b The \f{Help} menu can be used to read the \e{XTrackCAD} Help file.  Also, the \f{Help>Demos} menu selects a number of demonstrations which illustrate various features of \e{XTrackCAD}.

\u000

\b The \f{Options>Layout} menu specifies the working scale and overall room size.

\u000

\b The \f{Options>Preferences} menu specifies some less frequently changed items.
You can use this menu to choose Metric units (\K{cmdPref}).

\u000

\rule

The Tool Bar contains icons for each of the commands in the Menus. The icons shown can be customized using the \f{View->ToolBar} submenu.

\b The main drawing Mode command is \f{Select} - which is shown with the red arrow icon. From this mode, selected objects can be \f{Modified} as well. A close second is the \f{Describe} mode which allows properties of Objects to be seen and Changed.

\u000

\b A different mode is \f{Train} which allows trains to be simulated on the Layout.

\u000

Under the Tool Bar is the Hot Bar. This contains defined track and drawing objects taken from parameter files. To use a template you select it and then click on the Drawing Area.

\rule

The main part of the window is the Drawing Area, this is where the Layout is shown in 2D. The view can be zoomed or panned. The \f{Pan-Zoom} command whise symbol is the crossed arrows allows easiest control, but in \f{Select} command you can pan with the arrow keys and zoom with the trackpad or mousewheel or \f{Ctrl}+"+" or "-" can affect the zoom level.

\rule

At the bottom on the screen are two more areas. The Status Bar contains messages about commands as they are being used, and the Info Bar shows the zoom level and the position of the cursor.

\rule

\H{performance} Performance Issues

This section lists some things that can improve the performance of \e{XTrackCAD}.


\b On the \f{View} dialog (\K{cmdView}) turn off \f{Show Snap Grid} or \f{Change Grid...} to have fewer grid points.

\u000

\b To speed up initialization, remove unused parameter files (See \f{Parameter Files} dialog - \K{cmdPrmfile}).

\u000

\b Close the \f{Map} window if you don't need it to move about the layout.  The \f{Window} (\K{windowM}) menu can be used reopen the Map window.

\u000

\b On the \f{Display} dialog (\K{cmdDisplay}) turn off drawing \f{Endpoints}, decrease the \f{Two Rail Scale}, increase \f{Min Grid Spacing}, set \f{Draw Ties} to \f{None} and turn off \f{Live Map}.

\rule

\H{directories} Files and Directories

Information within this section of the manual identifies installation directory names, file names and directory and file locations.

\rule

\S{dirOverview} \i{Directories Overview}

\e{XTrackCAD} uses two directories on your system:

\b The \e{XTrackCAD Install} directory, which contains the data and parameter files used by \e{XTrackCAD}.

\u000

\b The \e{XTrackCAD Working} directory, which contains configuration and Check Point files.

On MS Windows, the \e{Install} directory is set when you install \e{XTrackCAD}. All data files (parameters,
demos, examples) can be found in the \c{share/xtrkcad} subdirectory underneath the \e{Install} directory.
The \e{Working} directory is in your personal profile.

On Linux, the \e{Install} directory is usually \c{/usr/local/lib/xtrkcad/}, but you can change this by defining the \c{XTRKCADLIB} environment variable before starting \e{XTrackCAD}. The working directory is \c{\{HOME\}/.xtrkcad/}.

On Mac OSX, the \e{Install} directory is the application package, usually located in the \c{/Applications} directory.
All the included parameters, demos and examples can be found inside the package under the  \c{/Applications/xtrkcad/Contents/Resources/xtrkcad} directory.
The \e{Working} directory is created as \c{.xtrkcad} - a hidden directory - under the active user's directory in \c{/Users}

Layout files (\c{*.xtc}) and export (\K{cmdExport}) files (\c{*.xti}) can be saved anywhere you wish, as specified in the \f{Save File} and \f{Open File} dialogs.

In MacOS Catalina, the program has no access to certain directories - the Documents and Download directories in particular.

Example layouts can be found in the \c{example} directory under the \e{XTrackCAD} install directory.

\rule

\S{installDir} \i{Install Directory}

\b \c{xtrkcad.xtq} is the main parameter file which contains definitions for each scale.  It also includes turnout definitions for the demos and lists the playback (\e{.xtr}) files for the demos.

\u000

\b \c{params} directory contains \c{*.xtp} files which are the \e{XTrackCAD} Library parameter files.  These files (\c{atlasn.xtp, pecon55.xtp, ...}) contain definitions for turnouts, sectional track pieces and structures.  These files to be used are selected in the \f{Parameter Files (\K{cmdPrmfile})} dialog.

\u000

\b \c{xtrkcad.chm} (on MS-Windows) is the \e{XTrackCAD} help file.

\u000

\b \c{xtrkcad.exe} (MS-Windows) or \c{xtrkcad} (Linux or Mac OSX) is the \e{XTrackCAD} program.

\u000

\b \c{xtrkcad.tip} contains the Tip of the Day information accessible from the \f{Help} menu or shown during startup.

\u000

\b \c{xtrkcad0.ini} specifies the location of the \e{XTrackCAD} working directory (MS-Windows only).

\u000

\b \c{demos} directory contains \c{*.xtr} which are the \e{XTrackCAD} demonstration files which can be run via the \f{Help>Demos} menu item.

\u000

\b \c{examples} directory contain some example \c{.xtc} files

\rule

\S{workDir} \i{Working Directory}

\b \c{xtrkcad.ckp} are the \e{check-point} files created periodically while running \e{XTrackCAD}.  If your system \e{XTrackCAD} hangs or crashes you get the choice of loading the checkpoint file and so recover (most of) your work by saving it to your current layout file.

\lcont{

The check-point frequency is set by the \e{Check Point} field found in the \f{Preferences} dialog (\f{Options>Preferences}).

}

\b The \c{xtrkcad.cus} file contains parameter information.  This is mostly information created by the \f{Turnout Designer} dialogs (\K{cmdTurnoutNew}) and \f{Group} (\K{cmdGroup}) command.  You can use the \f{Edit>Custom Management} dialog to manipulate these parameters.

\u000

\b The \c{xtrkcad.ini} (on MS-Windows) or the \c{xtrkcad.rc} (on Linux or Mac OSX) file contains various parameter settings from each use of \e{XTrackCAD}.  Most changes you make (such as scale, room size, window position) are saved in this file for the next time you use \e{XTrackCAD}.

\rule

\H{uninstall} \i{Removing \e{XTrackCAD}}

Remove \e{XTrackCAD} by deleting the \e{XTrackCAD Install} directory, or application (on Mac OSX), deleting any \c{xtrkcad.*} files from the \e{Working} directory, and deleting any \e{*.xtc} and \e{*.xti} files.

On MS-Windows only, you can also use the \f{Uninstall} icon in the \e{XTrackCAD} program group.

\rule


\H{bugs_enhancements} Bugs and Enhancements

This section of the manual describes how and where to report a bug or seek an enhancement.

\rule


\S{bugs} Reporting \i{Bugs}

If you encounter an unreported bug please submit detail regarding such to the \f{Bug Tracker} located at the \W{https://sourceforge.net/p/xtrkcad-fork/bugs/}{\e{XTrackCAD} Fork Project Site}.

\f{Be sure to provide the three basic elements of a bug report:} What you were doing at the time the bug occurred,  what you expected to happen and what actually happened. This detail will help developers replicate the error, find and correct the offending code.

\dt \f{A Sample Bug Report Follows;}

\u000

\dd After completing installation of  \e{XTrackCAD} on a Dell PC with 1024 MB of memory running Windows 7, the following error occurred when attempting to edit a Text Label;

\u000

\dd \c{Notice: allocateButt: Can't find 13. Do you want to save the layout?}

\u000

\dd Selecting either "Yes" or "No" results in a Windows error and \e{XTrackCAD} closes.

\u000

\dd The error can be replicated by opening the file named cascade.xtc. Set the magnification at 4:1. Attempting to move the text label named "Granville Island" located at the approximate grid coordinates of x=8", y=4' 5". Selecting the label causes the error to occur.

\u000

\dd The error is repeatable with other files contain text labels.

\f{Always search the bug database first.} Advice so good, we'll repeat it twice. Always search the bug database first. The odds are good that if you've found a problem, someone else found it too. If you spend a few minutes of your time making sure that you're not filing a duplicate bug, that's a few more minutes someone can spend helping to fix that bug rather than sorting out duplicate bug reports.

\f{If you don't understand an error message, ask for help.} Don't report an error message you don't understand as a bug. There are a lot of places you can ask for help in understanding what is going on before you can claim that an error message you do not understand is a bug. (Once you've understood the error message and have a good suggestion for a way to make the error message clearer, you might consider reporting it as a  \W{https://sourceforge.net/p/xtrkcad-fork/feature-requests/}{\e{XTrackCAD} Feature Request}).

\f{Please be brief, but don't leave any important details out.} This is a fine line to walk. But there are some general guidelines:

Remember the three basics: what you were doing, what you expected to happen, and what happened.

If you can recreate the problem the \f{Macro>Record} command can be used to record what happened.  Try to isolate the problem by creating a minimal layout and recording as few commands as possible.

\f{Don't report bugs about old versions.} Every time a new version of \e{XTrackCAD} is released, many enhancements are added and known bugs are fixed. If you're using a version of \e{XTrackCAD} that's more than two revisions older than the latest version, you should upgrade to the latest version to make sure the bug you are experiencing still exists. (It's not a bad idea to upgrade even if your version is only a version behind the most current one.)

\f{Only report one problem in each bug report.} If you encounter two or more bugs that don't appear to be related create a separate bug report for each one. This makes the task of managing work assignments easier and may result in a quicker fix for the problem.

\rule


\S{enhancements} \i{Enhancement Requests}

Suggestions for improvements are encouraged and welcome. Submit your suggestion to the \e{XTrackCAD} \f{Feature Tracker} located at the \W{https://sourceforge.net/p/xtrkcad-fork/feature-requests/}{\e{XTrackCAD} Fork Project Site}.

\S{support} \i{User Support}

The developers maintain a forum \W{https://xtrackcad.groups.io/g/main}{\e{XtrackCAD} User Forum} a Wiki at \W{http://www.xtrkcad.org/Wikka/HomePage}{\e{XTrackCAD} Wiki}

\rule