Merge remote-tracking branch 'upstream/master' into menu-options07a

Author: Chris Jakeman

Source/Contrib/SimulatorTester/Program.cs

@@ -23,6 +23,7 @@
 using System.IO;
 using System.Windows.Forms;
 using Orts.Common;
+using System.Diagnostics;
 
 namespace SimulatorTester
 {
@@ -31,9 +32,35 @@ internal class Program
         static void Main(string[] args)
         {
             var options = args.Where(a => a.StartsWith("-") || a.StartsWith("/")).Select(a => a.Substring(1));
-            var files = args.Where(a => !a.StartsWith("-") && !a.StartsWith("/"));
+            var files = args.Where(a => !a.StartsWith("-") && !a.StartsWith("/")).ToList();
             var settings = new UserSettings(options);
 
+            if (files.Count != 1 || options.Contains("help", StringComparer.InvariantCultureIgnoreCase))
+            {
+                var version = FileVersionInfo.GetVersionInfo(Application.ExecutablePath);
+                Console.WriteLine("{0} {1}", version.FileDescription, VersionInfo.VersionOrBuild);
+                Console.WriteLine();
+                Console.WriteLine("Usage:");
+                Console.WriteLine("  {0} [options] <save-file>", Path.GetFileNameWithoutExtension(Application.ExecutablePath));
+                Console.WriteLine();
+                Console.WriteLine("Options:");
+                Console.WriteLine("  <save-file>  {0} save file to use", Application.ProductName);
+                Console.WriteLine("  /quiet       Do not show summary of simulation (only exit code is set)");
+                Console.WriteLine("  /verbose     Show version and settings (similar to a {0} log)", Application.ProductName);
+                Console.WriteLine("  /fps <fps>   Set the simulation frame-rate [default: 10]");
+                Console.WriteLine("  /help        Show help and usage information");
+                Console.WriteLine("  ...and any standard {0} option", Application.ProductName);
+                Console.WriteLine();
+                Console.WriteLine("The {0} takes a save file and:", version.FileDescription);
+                Console.WriteLine("  - Loads the same activity as contained in the save file");
+                Console.WriteLine("  - Runs the simulation at the specified FPS for the same duration as the save file");
+                Console.WriteLine("  - Compares the final position with that contained in the save file");
+                Console.WriteLine();
+                Console.WriteLine("The exit code is set to the distance from the target in meters");
+                Console.WriteLine();
+                return;
+            }
+
             if (settings.Verbose)
             {
                 Console.WriteLine("This is a log file for {0}. Please include this file in bug reports.", Application.ProductName);
@@ -53,7 +80,7 @@ static void Main(string[] args)
                 LogSeparator();
             }
 
-            var saveFile = files.First();
+            var saveFile = files[0];
             using (BinaryReader inf = new BinaryReader(new FileStream(saveFile, FileMode.Open, FileAccess.Read)))
             {
                 var cts = new CancellationTokenSource(() => { });

Source/Documentation/Manual/driving.rst

@@ -170,7 +170,7 @@ tank, then the refilling takes place as the key is held down. If the
 locomotive is further away, then the distance to the nearest pickup is 
 shown instead.
 
-Note also that the key ``<Shift+T>`` will provide immediate refill 
+Note also that the key ``<Ctrl+T>`` will provide immediate refill 
 at any time.
 
 Specific Features to Optimize Locomotive Driving
@@ -633,7 +633,7 @@ within the cabview, see :ref:`here <cabs-odometer>`.
 .. _debriefeval:
 
 
-Debrief Evaluation
+Activity Evaluation
 ------------------
 
 ``Description``
@@ -643,15 +643,14 @@ This feature displays a real-time evaluation of the player's performance
 during the activity run and a final report at the end of an activity.
 The evaluation reports various parameters to provide to the player info in order 
 to improve his train driving ability.
-While the activity is running relevant data are stored and displayed.
-The stored data are used to generate a report at the end of the activity.
+While the activity is running, relevant data are stored and displayed.
+The stored data is used to generate a report at the end of the activity.
 
 
 ``How It Works``
 ''''''''''''''''
 
-Activity evaluation is enabled only for Activity mode, and requires the 
-"Debrief evaluation" checkbox in the main menu window to be enabled.
+Activity evaluation is enabled only for Activity mode.
 Checking some checkboxes within the various option tabs of the main menu 
 provides additional parameters for the activity evaluation. 
 
@@ -664,23 +663,11 @@ and here an example about the Options/Simulation tab:
 .. image:: images/dbfeval-options-simulation.png
 
 Checkboxes shown as unchecked in the two above pictures may be checked or 
-unchecked, but don't have effect to activity evaluation.
+unchecked, but don't have any effect on activity evaluation.
 
 A tab named "Evaluation" is present on the F1 Help Information Monitor.
 Once the activity is running it displays dynamic information about the player 
 train performance up to that moment.
-
-If the "Debrief evaluation" checkbox is unchecked, a message reminds this.
-
-   
-
-.. image:: images/dbfeval-evaluation-unchecked.png
-   :scale: 100%
-   :align: center
-
-
-In case that Debrief evaluation was checked, **Actual status: (**\ |darr| **)**\ , is displayed.
-
 
 
 .. image:: images/dbfeval-evaluation-ini.png
@@ -691,7 +678,7 @@ In case that Debrief evaluation was checked, **Actual status: (**\ |darr| **)**\
 
    \newpage
 
-Clicking **Actual status: (**\ |darr| **)**\  expanded real-time display appears.
+Clicking **Actual status: (**\ |darr| **)**\  shows an expanded real-time display.
 
 
 .. image:: images/dbfeval-evaluation-expanded.png
@@ -702,8 +689,6 @@ Clicking **Actual status: (**\ |darr| **)**\  expanded real-time display appears
 
 Clicking **Actual status: (**\ |uarr| **)**\  collapses all items.
 
-Once the activity has ended, the report file is created and a new window displays it.
-
 .. image:: images/dbfeval-evaluation-ended.png
    :scale: 100%
    :align: center
@@ -713,6 +698,9 @@ Once the activity has ended, the report file is created and a new window display
 
    \newpage
 
+Once the activity has ended, as soon as the player views the Evaluation tab, a report file is 
+created and shown in an editor window as follows.
+
 This report is made up of several sections.
 
 .. image:: images/dbfeval-report.png
@@ -721,15 +709,12 @@ This report is made up of several sections.
 
 .. raw:: latex
 
-    \newpage
+The report file OpenRailsEvaluation.txt is saved alongside the log file OpenRailsLog.txt and
+the default location for this is the Windows Desktop.
 
-Activity saves (F2) will save also the evaluation data, if the "Debrief evaluation" 
-checkbox was checked.
-In such case the activity saves will have the "Eval" checkbox checked in the resume window.
+The Save Game (F2) command also copies any evaluation report alongside the save files so it can be
+kept and reviewed. This copy is deleted when the other files for that save are deleted.
 
-.. image:: images/dbfeval-resume.png
-   :scale: 100%
-   :align: center
 
 .. _driving-hud:
 
@@ -1224,6 +1209,38 @@ and the wagon can be rotated or translated.
 It is suggested to read also :ref:`this paragraph <features-route-turntable-operation>` 
 to better understand what is possible with turntables and transfertables.
 
+.. _driving-containers:
+
+Loading and Unloading Containers
+================================
+
+Provided that the wagons and the container cranes in the route fulfill the rules indicated 
+:ref:`here<features-containers>`,  containers can be unloaded and loaded on wagons at 
+locations where a container crane is present.
+
+.. image:: images/driving-containers.png
+
+The loading and unloading operations are started by the player, by pressing the key ``<T>`` 
+for loading, and the key  ``<Shift-T>`` . The operation is performed on the first wagon 
+(starting from the locomotive) which is within the container crane displacement range and which 
+fulfills the required conditions (e.g. loading space available for loading, container present 
+for unloading). So, if a train has only empty wagons and the locomotive is within the container 
+crane displacement range, the first wagon is loaded first, then the second and so on up to the 
+last wagon within the crane displacement range. At that point, if there are further 
+wagons to be loaded, the train must be moved forward so that a new group of wagons is within 
+the crane displacement range, and Load operations can be resumed.
+
+Every keypress loads or unloads a single wagon. 
+
+In some cases it can occur that during a load operation the crane stops motion and the following 
+message appears on the display: ``"Wagon out of range: move wagon towards crane by {0} metres"``; 
+this occurs when the wagon is at the boundary of the crane displacement range; the player must 
+move the wagon towards the inside of the crane displacement range and stop the train. The crane 
+will then continue its loading mission up to the end.
+
+Saves (key ``<F2>``) are rejected and a message appears on the display when a loading 
+or unloading operation is ongoing.
+
 .. _driving-autopilot:
 
 Autopilot Mode