Update upstream source from tag 'upstream/5.2.2GA'

Update to upstream version '5.2.2GA'
with Debian dir 9c80045d0b4f9e463647bc8af8c090a673df4132

1 files changed, 78 insertions, 19 deletions

diff --git a/app/doc/filem.but b/app/doc/filem.but
index a0cce82..2fa4dba 100644
--- a/app/doc/filem.but
+++ b/app/doc/filem.but
@@ -29,7 +29,7 @@ The \f{File Menu} shows file oriented commands for loading and saving layout fil
 
 \u000
 
-\dd \f{Export to Bitmap} - Creates a bitmap file (\K{cmdOutputbitmap}) of the layout. The bitmap will be saved in PNG format.
+\dd \f{Export to Bitmap} - Creates a bitmap file (\K{cmdOutputbitmap}) of the layout. The bitmap can be saved in either JPEG or PNG format.
 
 \u000
 
@@ -37,6 +37,11 @@ The \f{File Menu} shows file oriented commands for loading and saving layout fil
 
 \u000
 
+\dd \f{Export to SVG} - Exports the selected objects to a file in SVG format. The exported file can then be imported into a vector drawing program like Inkscape 
+or used for publishing on the web.
+
+\u000
+
 \dd \f{File List} - List of the five most recently used \e{XTrackCAD} files or archives.
 
 \u000
@@ -100,14 +105,21 @@ This menu item creates a bitmap file of the layout.
 
 \G{png.d/bitmap.png}
 
-The \f{Bitmap} dialog specifies the style and size of the bitmap.  The three check-boxes (\f{Print Titles}, \f{Print Borders} and \f{Print Centerline}) control whether the Layout Title (\K{cmdLayout}), the borders or the track centerlines are printed on the bitmap.  The size of the bitmap is smaller if these are disabled.
+The \f{Bitmap} dialog specifies the style and size of the bitmap.  The check-boxes (\f{Layout Titles}, \f{Borders}, \f{Centerline of Track} and
+\f{Background Image}) control 
+whether the Layout Title (\K{cmdLayout}), the borders or the track centerlines are printed on the bitmap. If a background image is used it will be
+printed if the option is set. 
+
+ The size of the bitmap is smaller if these are disabled.
 
 Printing the track centerlines (also seen when zoomed in 1:1) is useful when you later print the bitmap
 full size for laying out track.
 
 If the Snap Grid (\K{cmdGrid}) is visible then it will be printed on the bitmap.
 
-The \f{DPI} (or \f{DPCM} if using metric units (\K{cmdPref})) control specifies the number of pixels per inch (or centimeter) in the bitmap.  You can enter values from 0.1 to 100.  Larger values will result in a larger bitmap file.  bitmaps must be less than 32000 pixels in height or width.
+The \f{DPI} control specifies the number of pixels per inch in the bitmap.  Bitmaps must be less than 32,000 pixels in height or width. 
+The upper value you can enter depends on the size of your trackplan. It is made sure that your bitmap does not exceed these limits.
+Larger values will result in a larger bitmap file.  
 
 The bitmap width, height and approximate file size is indicated.
 
@@ -115,7 +127,8 @@ Note: This command can create a very large file and consume a lot of memory and
 
 Pressing the \f{OK} button invokes a \f{File Save} dialog so you can choose the file name for the Bitmap.
 
-The format of the file is PNG on all operating systems.
+You can select to create JPEG or PNG files. As a rule of thumb JPEG results in smaller files  when you use a backgound image, PNG 
+does so for trackplans without an image background.
 
 \rule
 
@@ -129,6 +142,22 @@ Exported files can then be imported into other CAD programs.
 
 \rule
 
+\S{ExportSVG} \i{Export to SVG}
+
+This menu item displays a file selection dialog where a file name for exported objects can be entered.  All selected (\K{cmdSelect}) objects are exported to the file. The export file will have an \c{svg} extension.
+
+Files in SVG format can be used for different purposes. 
+
+\b SVG files can be loaded into many drawing programs. This makes it possible to enhance and resize the image. Vector images have the advantage of 
+allowing lossless resizing.
+
+\b Most modern browsers support SVG as an image format. So the resulting file can directly be used to publish your plan on the web. By adding a bit of 
+Javascript, zooming and panning can be enabled. Appropiate scripts can easily be found using your favorite search engine. 
+The generated SVG uses the layout description as a title that is shown by some browser. Also the drawing has an 'id' for manipulation by Javascript. 
+This id is derived from the filename by removing all spaces and sticking the word 'id' in front. Eg exporting \c{stonega.xtc} the resulting id will be \c{idstonega}.
+
+\rule
+
 \S{cmdImport} Import
 
 Importing displays a file selection dialog to specify the file to import.
@@ -149,26 +178,27 @@ The dialog contains a list of parameter files. Each file is preceded by a color
 are usable in the current scale and gauge.
 
 \G{png.d/greendot.png} \G{png.d/greenstar.png} Definitions from this file are a perfect fit for the current layout options. The file has been loaded and will be visible in the \f{HotBar}. For track this means that gauge and scale of the track elements
-are identical to the layout settings.
+are identical to the layout settings. Prototype definitions (Scale "*") are always a perfect fit. Turnouts and Sectional Track must have the same gauge and usually the same scale unless the scale/gauge combination has been defined to fit. 
+OO layouts use HO track as an example.
 
 \G{png.d/yellowdot.png} \G{png.d/yellowstar.png} Definitions from this file can be used with this layout but do not fit perfectly. A typical example is On30 where HO scale track can be used because the
-gauge is the same. But differences in scale may make the track look out of scale.
+gauge is the same. But differences in scale may make the track look out of scale. Structures are considered compatible if the scale is within +/-20%. Cars are compatible if the gauge is the same, but the scale can be +/-20%. 
+Exceptions to this can be defined in the scale definitions.
 
 \G{png.d/reddot.png} \G{png.d/redstar.png} This parameter file doesn't contain any usable definitions with current settings. You may want to change the layout options if you want to use elements from
 this file (for example altering the Layout Scale).
 
 \G{png.d/greydot.png} \G{png.d/greystar.png} This file is loaded but hidden.
 If it is marked as favorite it will be kept on the
-list between runs. Otherwise it will be removed from the list when
-the program is terminated.
+list between runs. 
 
-Definition files can be marked as \e{favorite}. The indicator for favorites is a star.
+Parameter files can be marked as \e{favorite}. The indicator for favorites is a star.
 The meaning of the colors isn't changed.
 
 Loaded definition files that are marked with a yellow or a green indicator appear on the \f{Hot Bar} (\K{cmdHotBar}).  
 
 If you \e{unload} a file the definitions are removed from the selection lists and the \f{Hot Bar}.  
-If the unloaded file was marked as a favorite it can be \e{reloaded} by selecting the  \f{Reload} button.
+If the unloaded file was marked as a favorite it can be \e{reloaded} by selecting the \f{Reload} button.
 
 Files that are still loaded can be \e{reloaded} as well. In that case the old definitions are refreshed and extended by the 
 rereading the file. This can be useful if you want to check changes you made by hand-editing a parameter file. 
@@ -189,7 +219,7 @@ It is the equivalent of using \f{Browse} and selecting the file again.
 Files can be listed by either their file name or by their contents description.
 This is controlled by the \f{Show File Names} check box.
 
-The \f{Search} button opens the \e{Search Parameter File} dialog (\K{cmdSearchgui}) this
+The \f{Library} button opens the \e{Choose Parameter File} dialog (\K{cmdSearchgui}) this
 shows the all files included the system library so they can be added.
 
 The \f{Browse} button opens a file window that allows the user to add additional files
@@ -203,18 +233,23 @@ The order in this list controls the order of turnouts and structures on the
 \f{Hot Bar} (\K{cmdHotBar}). You can move a parameter file to the end of the
 list by \e{Unloading} it, and then loading it via the \f{Browse} button.
 
-\S{cmdSearchgui} \i{Search Parameter Files}
+\S{cmdSearchgui} \i{Choose Parameter Files}
 
 Selecting and loading additional parameter files from the System Library is done in the
-\f{Search Parameter Files} dialog.
+\f{Choose Parameter Files} dialog.
 
 \G{png.d/paramsearch.png}
 
 Using the Search function you can find and select parameter files that are
 part of the XTrackCAD installation.
-Enter a search string and select the Search button. Search results are
-shown in the list box. A blank search or the value "*" resets the search results to 
-show the entire libary. 
+Enter a set of one or more words and select the Search button. Search results are
+shown in the list box. Pressing the \i{Clear Filter} button shows the complete
+list again. 
+
+You can subset the search to only search for parameter files who start with contents that fit the current Layout Scale using the \f{Fit} Mode. 
+The options are "Fit All", "Fit Compatible" and "Fit Exact".  Fit Compatible means that structures with 
+Note that the code only looks at the first Turnout, Structure or Car entry to decide on the scale for the entire file.
+They will correspond to the color icons on the Parameter Files menu once they are loaded \K{cmdPrmfile} when the same Layout scale is in use.
 
 Select the files you're interested in and press the \f{Add} button to add them to your
 parameter list.
@@ -279,7 +314,8 @@ Whether tracks are printed with one or two lines (representing the center line a
 
 \u000
 
-\dd \f{Page Numbers} - to help positioning the individual pages the page number is printed in the center of the page in the format (x/y). x is the position from left to right, y in from bottom to top, So (1/1) is the page at the bottom left.
+\dd \f{Page Numbers} - to help positioning the individual pages the page number is printed in the center of the page in the format (x/y). 
+x is the page position from left to right, y in from bottom to top, So (1/1) is the page at the bottom left.
 As an additional aid, the numbers of the next pages are printed on each edge.
 
 \u000
@@ -288,7 +324,7 @@ As an additional aid, the numbers of the next pages are printed on each edge.
 
 \u000
 
-\dd \f{Rulers} - print rulers on all edges of the page.  This option is only enabled if the \f{Angle} is \e{0.000}.
+\dd \f{Rulers} - choose to print rulers at the layout edge, or on all edges of the page, an option is only enabled if the \f{Angle} is \e{0.000}, or None - which means print no rulers.
 
 \u000
 
@@ -377,6 +413,29 @@ The \f{Printer Setup} window contains:
 
 \dd \f{Cancel} - ends the dialog without update.
 
+\u000
+
+\e{Note} - 
+Printing uses a default of 600ppi. It scales the print and text from a default size of 72dpi. 
+This is often the expected value for a standard printer driver to work correctly, but will not work if the driver is not accurately setting the ppi available.
+To override the printer ppi you can use either the configuration file settings for print or environmental variables. 
+These values are set in the Preferences section.
+\u000
+
+\n Preferences.PrintScale - The floating point ratio of the real printer dpi to 72. 
+
+\n Preferences.PrintTextScale - The floating point ratio of the real printer text support to a dpi of 72. This value has no effect unless PrintScale is set to > 0.0.
+
+\u000
+These values can also be set using environmental variables if the configuration preference values are not set or they are set to <=0.0. 
+\u000
+
+\n XTRKCADPRINTSCALE
+
+\n XTRKCADPRINTTEXTSCALE
+
+\u000
+
 \rule
 
 \S2{MS-Windows} \i{Microsoft Windows}
@@ -441,7 +500,7 @@ To check your printer's margin:
 
 \u000
 
-\dd Enable \f{Registration Marks}
+\dd Enable \f{Registration Marks} this prints crosshairs every 6" at scale 1:1. 
 
 \u000