From 03e89dc973b9532e1b6c1afd1ae2aa40386130dc Mon Sep 17 00:00:00 2001
From: WrinklyNinja <wrinklyninja1@gmail.com>
Date: Thu, 13 Jun 2013 00:25:12 +0100
Subject: [PATCH] More error handling, layout tweaks, and updated readme.

---
 docs/BOSS Readme.html | 109 +++++++++++++++++++++++++++++++++---------
 src/gui/main.cpp      |  24 +++-------
 2 files changed, 93 insertions(+), 40 deletions(-)

diff --git a/docs/BOSS Readme.html b/docs/BOSS Readme.html
index 6678436d..aed259ca 100644
--- a/docs/BOSS Readme.html	
+++ b/docs/BOSS Readme.html	
@@ -39,7 +39,7 @@ h3{
     a[href^="http"]:after {padding-left:2px; content: url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAAVklEQVR4Xn3PgQkAMQhDUXfqTu7kTtkpd5RA8AInfArtQ2iRXFWT2QedAfttj2FsPIOE1eCOlEuoWWjgzYaB/IkeGOrxXhqB+uA9Bfcm0lAZuh+YIeAD+cAqSz4kCMUAAAAASUVORK5CYII=);}
 
     span[title] {border-bottom: 1px dotted; font-family: sans-serif; cursor:help;}
-    abbr {cursor:help;}
+    abbr {cursor:help; border-bottom: 1px dotted black;}
 
     #warning {background:#fbb; padding:10px 5px;margin:-8px;}
     .warning {background:#fbb; padding:10px; border-color:#d00;}
@@ -53,7 +53,8 @@ h3{
     td.c:after {content: '\2717';}
     tr.inactive {color:#888;}
     tr.inactive td.c, tr.inactive td.t {background:#E3E3E3;}
-
+    dt {margin-bottom:0.5em; margin-top:1em; font-style:italic;}
+    dd {margin-bottom:0.75em;}
 </style>
 <!--  BOSS
 
@@ -96,6 +97,10 @@ This documentation is a work in progress, covering an application that is also s
         <li><a href="#usage-log">The Results Report</a>
     </ol>
     <li><a href="#trouble">Troubleshooting</a>
+    <ol>
+        <li><a href="#trouble-general">General Issues</a>
+        <li><a href="#trouble-errors">Error Messages</a>
+    </ol>
     <li><a href="#contrib">Contributing To BOSS</a>
     <li><a href="#translate">Translating BOSS</a>
     <ol>
@@ -128,16 +133,17 @@ This documentation is a work in progress, covering an application that is also s
 
 <h2 id="install">Installation &amp; Uninstallation</h2>
 
-<blockquote class="warning">BOSS version 3 is not backwards compatible with version 2, as it makes a variety of major changes to how BOSS works. In particular, it will almost certainly set a different load order, and any user rules will have to be manually recreated in BOSS's user interface. Version 2 should be uninstalled prior to installing version 3.</blockquote>
+<blockquote class="warning">BOSS version 3 is incompatible with earlier versions, which should be removed. Any existing user rules must be manually recreated in BOSS's user interface.</blockquote>
 
-<p>The simplest way to install BOSS is to use the installer. However, the instructions below are provided if a manual install method is preferred.
+<p>BOSS can be installed either using its automated installer or manually. To install BOSS manually:
 <ol>
-    <li>If updating from an earlier version of BOSS, uninstall the existing BOSS install before continuing. Any userlists you have should be moved to a temporary location while you install the BOSS update.
-    <li>Extract the <q>BOSS</q> folder the downloaded archive contains to a location of your choice. Make sure that you have the appropriate file permissions for the directory you choose. See the <a href="#appendix-permissions">File Permissions</a> section for more information.
-    <li>If any of the <abbr title="Wrye Bash, Wrye Flash or Wrye Flash NV">Wrye *ash</abbr> utilities are installed, make sure their <q>BOSS Disable Lock Load Order</q><span title="previously BOSS Disable Lock Times">*</span> setting is enabled.
-    <li>If updating from an earlier version of BOSS and you moved any userlists you have to a temporary location, after you have run BOSS at least once for each game with a userlist, you will need to move your userlist(s) into the game(s) subfolders that are created within the BOSS folder.
+    <li>Extract the downloaded archive to a location of your choice.
+</ol>
+<p>If BOSS was installed using the installer, then use the uninstaller linked to in the Start Menu to uninstall BOSS. If BOSS was installed manually:
+<ol>
+    <li>Delete the files you extracted from the location you chose.
+    <li>Delete the <q>BOSS</q> folder in your local application data folder, which can be accessed by entering <code>%LOCALAPPDATA%</code> into Windows' File Explorer.
 </ol>
-<p>If BOSS was installed using the installer, then use the uninstaller it provides a link to in the Start Menu to uninstall BOSS. If BOSS was installed manually, simply delete the <q>BOSS</q> folder you installed and the BOSS folder in your local application data folder, which can be accessed by entering <code>%LOCALAPPDATA%</code> into Windows' File Explorer.
 
 
 <h2 id="usage">Using BOSS</h2>
@@ -151,9 +157,55 @@ This documentation is a work in progress, covering an application that is also s
 <p>Clicking the <q>View Last Report</q> button will display the <a href="usage-log">report</a> generated the last time BOSS sorted your plugins.
 <p>The <q>File</q> menu provides menu items for sorting plugins, viewing the last report BOSS generated and quitting BOSS, while the <q>Edit</q> menu provides menu items for accessing BOSS's metadata editor and the <a href="usage-settings">settings window</a>.
 <p>The <q>Game</q> menu allows you to change which game BOSS is running for without having to close and re-open it. Games that BOSS cannot find are greyed out, and the the one BOSS is running for is marked with a dot to its left. To change the active game, simply select another game in the list.
-<p>The <q>Help</q> menu provides a link to this readme and an about page that contains the version of BOSS being run, some legal information and a link to the project repository.
+<p>The <q>Help</q> menu provides a link to this readme and an about page that contains the version of BOSS being run, some legal information and a link to the <a href="http://code.google.com/p/better-oblivion-sorting-software/">project repository</a>.
 
 <h3 id="usage-sort">Sorting Plugins</h3>
+<figure>
+    <img src="images/confirm.png">
+    <figcaption>Editing BOSS's calculated load order.</figcaption>
+</figure>
+<p>Clicking the <q>Sort Plugins</q> button in the main window will begin the sorting process, which consists of the following steps:
+<ol>
+    <li>Provided that masterlist updating <a href="#settingsUpdateMasterlist">is enabled</a> and that an online masterlist URL <a href="#settingsMasterlistURL">is set</a>, BOSS checks for updates to its masterlist and downloads any that are available. If there are any syntax errors in the latest masterlist (due to human error by its maintainers), the updater rolls back one version at a time until it finds a version that works. If any other errors are encountered, updating is cancelled. Details of any errors encountered will be supplied in BOSS's report.
+    <li>The game's Data folder is scanned for plugins, including those ghosted by <abbr title="Wrye Bash, Wrye Flash or Wrye Flash NV">Wrye *ash</abbr>. The contents of each plugin are read to obtain data such as: whether or not it is a master file; the FormIDs of the records it contains; what its masters are; any Bash Tags that are applied; and any version number it has been given in its description.
+    <li>The masterlist and userlist are read. Any errors encountered will be detailed in BOSS's report.
+    <li>For each plugin, any userlist data present is merged down to any masterlist data present, which is then in turn combined with the data read from the plugin.
+    <li>For each plugin, any data conditions are evaluated and irrelevant data discarded. Any errors encountered during evaluation will be detailed in BOSS's report.
+    <li>The self-consistency of the plugin data is checked to ensure that there are no cyclic dependencies or dependencies that are also given as incompatibilities. If any such issues are present, sorting will not take place (as it becomes impossible), and the issues will be detailed in BOSS's report.
+    <li>Checks are performed to ensure that all dependencies are present in the game's Data folder, and that no incompatibilities are present. If a dependency is missing or an incompatibility is present, an error message will be displayed in BOSS's report.
+    <li>The plugins are sorted according to BOSS's sorting algorithm.
+    <li>The dialog shown above is displayed, allowing you to move plugins up or down the load order. The dialog allows multiple plugins to be selected and moved at once.
+    <li>If the <q>OK</q> button is pressed, the final load order will be applied. Otherwise, no load order changes will be made.
+    <li>BOSS's report will be generated and displayed either in a new window or in your default browser, according to the value of the <a href="#settingsViewReports">relevant setting</a>. See the next section for more information on the report.
+</ol>
+<p>Sorting around 90 plugins generally takes under 30 seconds, depending on the sizes of the plugins that are installed. For very large plugins, such as the game's main master file, BOSS may appear to stop responding while the plugin is read: this is not an issue.
+
+
+<h3 id="usage-log">The Results Report</h3>
+<figure>
+    <img src="images/viewer-1.png">
+    <img src="images/viewer-2.png">
+    <figcaption>BOSS's report viewer.</figcaption>
+</figure>
+<p>BOSS's results report can be displayed either in BOSS's own report viewer, or in your default web browser, according to the value of the <a href="#settingsViewReports">relevant setting</a>.
+<p>The report is comprised of two main sections:
+<ul>
+    <li>The <q>Summary</q> tab gives information on the versions of BOSS and the masterlist used, whether masterlist updating is enabled, and breaks down the numbers of each message type in the Summary and Details tabs. It also notifies you if there have been no changes in the <q>Details</q> tab since you last ran BOSS for the same game. Finally, the <q>Summary</q> tab is also where any global messages supplied in the masterlist and any errors encountered during sorting are displayed.
+    <li>The <q>Details</q> tab lists the plugins BOSS sorted in their new load order, along with any messages BOSS has provided for them. BOSS will also display plugin version according to what it found in each plugin's description field.
+</ul>
+<p>In addition, there are a few filters that can be used to selectively hide items in the <q>Details</q> tab. These filters are:
+<ul>
+    <li><i>Hide Version Numbers</i>: Hides the version numbers printed in blue next to those plugins that provide them.
+    <li><i>Hide Notes</i>: Hides all messages attached to plugins that have the <i>Note:</i> prefix.
+    <li><i>Hide Bash Tag Suggestions</i>: Hides all Bash Tag suggestions.
+    <li><i>Hide 'Do Not Clean' Messages</i>: Hides any messages that contain the string <q>Do not clean.</q>.
+    <li><i>Hide All Plugin Messages</i>: Hides all plugin messages.
+    <li><i>Hide Messageless Plugins</i>: Hides any plugins that have no visible messages.
+</ul>
+<p>BOSS will display the version numbers of any plugins that provide them in their description fields. If a plugin supplies no version number, it cannot be displayed. The version numbers may not reflect the actual version of the mod installed - this could either be due to the mod author forgetting to update the description, or due to a mistake in BOSS's detection. As version numbers are supplied by mod authors in a wide range of formats and BOSS has to detect as many as possible, it occasionally identifies parts of some descriptions as version numbers incorrectly. When in doubt, check the version number given in a mod's readme.
+<p>BOSS's mod messages are one of the most important features BOSS provides, acting as a means of providing users with information that they might otherwise not obtain. It is important for a stable, healthy game that you act on any messages that require action.
+<p>If you think a message suggests an unnecessary action, report it to an official BOSS thread. If you encounter a message that is non-conditional, ie. it suggests an action but is still displayed on subsequent runs of BOSS after the action has been carried out, or that it suggests an action that is not necessary, also report it to an official BOSS thread, so that it can be made conditional.
+
 
 <h3 id="usage-custom">Customising BOSS's Results</h3>
 <figure>
@@ -203,8 +255,6 @@ This documentation is a work in progress, covering an application that is also s
 </table>
 
 
-<h3 id="usage-log">The Results Report</h3>
-
 <h3 id="usage-settings">Editing Settings</h3>
 <figure>
     <img src="images/settings.png">
@@ -218,8 +268,8 @@ This documentation is a work in progress, covering an application that is also s
         <tr><td id="settingsDefaultGame">Default Game<td>If set to something other than <q>Autodetect</q>, this overrides game autodetection. If the game specified is not detected, BOSS falls back to autodetection.
         <tr><td>Language<td>Controls the language BOSS uses in its interfaces. Debug messages are always displayed in English, and any plugin messages that do not have translations in the selected language will be displayed in English instead.
         <tr><td>Debug Verbosity<td>Controls the verbosity of the debug output, which is written to <q>BOSSDebugLog.txt</q>.
-        <tr><td>Update masterlist before sorting<td>If checked, BOSS will update its masterlist, should an update be available, before sorting mods.
-        <tr><td>Viewer reports externally in default browser.<td>If checked, BOSS will display its report using your default web browser instead of opening its own window.
+        <tr><td id="settingsUpdateMasterlist">Update masterlist before sorting<td>If checked, BOSS will update its masterlist, should an update be available, before sorting mods.
+        <tr><td id="settingsViewReports">View reports externally in default browser.<td>If checked, BOSS will display its report using your default web browser instead of opening its own window.
 </table>
 <p>The games list allows the customisation of which games BOSS offers support for, trivialising support for multiple copies of a game and Total Conversions. The games listed here will be displayed in the main window's <q>Game</q> menu when BOSS is next run. The <q>Add Game</q>, <q>Edit Game</q> and <q>Remove Game</q> buttons are used to edit the list. Each game has several columns, which are explained below.
 <table>
@@ -234,9 +284,9 @@ This documentation is a work in progress, covering an application that is also s
             <li>Fallout 3
             <li>Fallout: New Vegas
         <ul>
-        <tr><td>BOSS Folder<td>The sub-folder which BOSS uses to store the game's files in. Each game must be given a unique sub-folder.
+        <tr><td>BOSS Folder Name<td>The sub-folder which BOSS uses to store the game's files in. Each game must be given a unique sub-folder.
         <tr><td>Master File<td>The game's main master file. This is specified as it must load before all other plugins. Note that Skyrim-based games will always load Skyrim.esm first, so this column must always be set to <q>Skyrim.esm</q> for such games.
-        <tr><td>Online Masterlist<td>The URL of the online masterlist that BOSS uses to update its local copy. 
+        <tr><td id="settingsMasterlistURL">Online Masterlist URL<td>The URL of the online masterlist that BOSS uses to update its local copy. If set to an empty string, masterlist updating will be skipped.
         <tr><td>Install Path<td>The path to the game's folder, in which the Data folder lies. 
         <tr><td>Install Path Registry Key<td>The registry key, in <code>HKEY_LOCAL_MACHINE</code>, that contains the install path of the game. This may be used to obtain the install path of a game the first time BOSS runs for it.
 </table>
@@ -244,10 +294,26 @@ This documentation is a work in progress, covering an application that is also s
 
 
 <h2 id="trouble">Troubleshooting</h2>
+<p>If BOSS encounters a problem at any point, it should provide an error message, either in a dialog (as is generally the case) or in its report (as for errors encountered during the sorting process). If BOSS unexpectedly crashes, or you experience a problem for which no error message is given, please report the crash or problem to an official BOSS thread (see <a href="#contrib">Contributing To BOSS</a>), so that it can be fixed.
+<p>If the information below does not help you to solve any problems you are experiencing, please seek further support in one of the official BOSS threads.
+<h3 id="trouble-general">General Issues</h3>
+<p>There are a few general reasons why BOSS may fail to function correctly. Check if any of the symptoms listed below fit your issue.
+<dl>
+    <dt>No change in load order.
+        <dd>Make sure that you aren't using another utility to <q>lock</q> your load order.
+    <dt>Some plugins have the wrong or no version number given in the BOSS Log.
+        <dd>No solution.
+    <dt>You get an error message of the form <q>There is a problem sending the command to the program.</q>
+        <dd>Windows sometimes does this when it tries to open files in their default application. If you're sure that you have a default program for HTML files set, restarting your computer generally fixes the issue.
+    <dt>A game is installed, but BOSS cannot detect it.
+        <dd>The game's Registry entry is missing. This happens to a lot of people, because Steam likes to remove it whenever the game is updated or its game cache is verified. Run the game's launcher to add the Registry entry back again.
+</dl>
+<h3 id="trouble-errors">Error Messages</h3>
+<p>If BOSS can detect a specific reason for being unable to function correctly, it will print an error message detailing the problem. BOSS's error messages are listed below, along with details of the issues and possible solutions.
 
 
 <h2 id="contrib">Contributing To BOSS</h2>
-<p>User contribution of additions and corrections to BOSS's metadata masterlist are vital to the upkeep of BOSS. Please let us know what you know!
+<p>User contribution of additions and corrections to BOSS's masterlists are vital to the upkeep of BOSS. Please let us know what you know!
 
 <p>General discussion and the submission of questions, suggestions and metadata takes place in BOSS's official threads for <a href="">Oblivion</a>, <a href="">Nehrim</a>, <a href="">Skyrim</a>, <a href="">Fallout 3</a> and <a href="">Fallout: New Vegas</a>.
 
@@ -268,7 +334,7 @@ This documentation is a work in progress, covering an application that is also s
 
 <h2 id="credits">Credits</h2>
 <p>As BOSS is very much a community project, credit is due to a very large number of sources and people outside of the BOSS Development Team. Some people have gone out of their way and provided continuing, expert and detailed help - <b>thank you very much</b>!
-<p>In addition to the above, the following are credited with application-related support:
+<p>In addition to the above data-related support, the following are credited with application-related support:
 <ul>
     <li><a href="http://www.darkcreations.org">Dark Creations</a>: For hosting BOSS's Bugzilla bug tracker that is used to collect anonymous unrecognised plugin reports. Particular thanks to its administrators Andalaybay and Xae for offering to host the tracker and helping to work around Firefox and Bugzilla bugs encountered.
     <li>Surazal: For extensive testing of v1.6+ prior to release and for providing the inspiration for many features through his BOSS Masterlist Manager macro for Microsoft Word.
@@ -292,7 +358,7 @@ This documentation is a work in progress, covering an application that is also s
 
 
 <h2 id="project">Project Members</h2>
-<p>Since June 2009, BOSS has been a collaborative project on Google Code using the Subversion version control system. In alphabetical order, the project members are:
+<p>Since June 2009, BOSS has been a collaborative project on <a href="http://code.google.com/p/better-oblivion-sorting-software/">Google Code</a> using the Subversion version control system. In alphabetical order, the project members are:
 <table>
     <thead class="c"><tr><th colspan="2" rowspan="2">Member<th rowspan="2">Admin<th rowspan="2">Programmer<th colspan="5">Masterlists Member Contributes To
         <tr><th>Oblivion<th>Nehrim<th>Fallout 3<th>Fallout: New Vegas<th>Skyrim
@@ -331,9 +397,8 @@ This documentation is a work in progress, covering an application that is also s
 
 <p>While the GPL license allows anyone to make derivative works of BOSS, the BOSS Development Team encourages those thinking of doing so to first discuss their reasoning for such an endevour with the Team. It may be that what the derivative work would do differently from BOSS itself is already planned for a future version of BOSS or would be happily integrated into BOSS by the Team, thus avoiding any extra effort by others.
 <p>The BOSS Team also appeals to the community to avoid the distribution and development of alternative masterlists, as this would only hamper the community effort to create one universally-optimised load order for all plugins available for download. Any issues with a masterlist are best brought to the attention of the BOSS Team so that we may remedy them ourselves.
-
-<h3>GNU Free Documentation License Version 1.3 Notice</h3>
-<blockquote>Copyright (C)  2009-2012  BOSS Development Team<br />
+<p>GNU Free Documentation License Version 1.3 Notice:
+<blockquote>Copyright (C)  2009-2013  BOSS Development Team<br />
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3
 or any later version published by the Free Software Foundation;
diff --git a/src/gui/main.cpp b/src/gui/main.cpp
index 3f682c54..3ed0f029 100644
--- a/src/gui/main.cpp
+++ b/src/gui/main.cpp
@@ -384,14 +384,7 @@ void Launcher::OnSortPlugins(wxCommandEvent& event) {
         try {
             mlist = YAML::LoadFile(_game.MasterlistPath().string());
         } catch (YAML::ParserException& e) {
-            //LOG_ERROR("Error: %s", e.getString().c_str());
-            wxMessageBox(
-				FromUTF8(format(loc::translate("Error: Masterlist parsing failed. %1%")) % e.what()),
-				translate("BOSS: Error"),
-				wxOK | wxICON_ERROR,
-				this);
-            progDia->Destroy();
-            return;
+            messages.push_back(boss::Message(boss::MESSAGE_ERROR, string("Masterlist parsing failed. Details: ") + e.what()));
         }
         if (mlist["globals"])
             mlist_messages = mlist["globals"].as< list<boss::Message> >();
@@ -409,14 +402,7 @@ void Launcher::OnSortPlugins(wxCommandEvent& event) {
         try {
             ulist = YAML::LoadFile(_game.UserlistPath().string());
         } catch (YAML::ParserException& e) {
-            //LOG_ERROR("Error: %s", e.getString().c_str());
-            wxMessageBox(
-				FromUTF8(format(loc::translate("Error: Userlist parsing failed. %1%")) % e.what()),
-				translate("BOSS: Error"),
-				wxOK | wxICON_ERROR,
-				this);
-            progDia->Destroy();
-            return;
+            messages.push_back(boss::Message(boss::MESSAGE_ERROR, string("Userlist parsing failed. Details: ") + e.what()));
         }
         if (ulist["plugins"])
             ulist_plugins = ulist["plugins"].as< list<boss::Plugin> >();
@@ -601,7 +587,9 @@ void Launcher::OnSortPlugins(wxCommandEvent& event) {
 
             //Now set load order.
             _game.SetLoadOrder(plugins);
-        }
+        } else
+            messages.push_back(boss::Message(boss::MESSAGE_WARN, "The load order displayed in the Details tab was not applied as sorting was canceled."));
+                cyclicDependenciesExist = true;
 
         out << "Set load order:" << endl;
         for (list<boss::Plugin>::iterator it=plugins.begin(), endIt = plugins.end(); it != endIt; ++it)
@@ -845,7 +833,7 @@ LoadOrderPreview::LoadOrderPreview(wxWindow *parent, const wxChar *title, const
     //Set up layout.
     wxBoxSizer * bigBox = new wxBoxSizer(wxVERTICAL);
 
-    bigBox->Add(_loadOrder, 1, wxEXPAND|wxLEFT|wxRIGHT|wxBOTTOM, 10);
+    bigBox->Add(_loadOrder, 1, wxEXPAND|wxALL, 10);
 
     wxBoxSizer * hbox = new wxBoxSizer(wxHORIZONTAL);
     hbox->Add(_moveUp, 0, wxRIGHT, 5);