More docs updates.

In particular, documented the new location data structure.

README.md

@@ -40,7 +40,7 @@ BOSS requires the following libraries:
 
 BOSS expects all libraries' folders to be present alongside the BOSS repository folder that contains this readme, or otherwise installed such that the compiler and linker used can find them without suppling additional paths. All paths below are relative to the folder(s) containing the libraries and BOSS.
 
-BOSS also requires GraphVis and Subversion binaries, which can be obtained [here](http://sourceforge.net/projects/win32svn) and [here](http://www.graphviz.org/Download_windows.php) respectively and should be installed as detailed below.
+BOSS can also make use of [GraphVis](http://www.graphviz.org/Download_windows.php) and [Subversion](http://sourceforge.net/projects/win32svn) binaries. If provided, they should be installed as detailed below.
 
 Alphanum, Libespm and PugiXML do not require any additional setup. The rest of the libraries must be built separately.
 

docs/BOSS Metadata Syntax.html

@@ -80,6 +80,7 @@ h3{
         <li><a href="#structs-file">File Data Structure</a>
         <li><a href="#structs-message">Message Data Structure</a>
         <li><a href="#structs-plugin">Plugin Data Structure</a>
+        <li><a href="#structs-location">Location Data Structure</a>
     </ol>
     <li><a href="#cond">Condition Strings</a>
     <ol>
@@ -103,10 +104,11 @@ h3{
 <p>Some important points that are more specific to how BOSS uses YAML:
 <ul>
     <li>Child data nodes should be indented two spaces from their parents. This isn't a strict requirement, but is the best trade-off between compactness and readability.
-    <li>Strings should be enclosed in single quotes if they contain any of the following characters: <code>-?:,[]{}#&amp;*!|&gt;"%@`</code>, unless they also contain any single quotes, in which case the string should be enclosed in double quotes instead. Any backslashes or double quotes within a double-quoted string should be escaped with a backslash, ie. <code>"</code> &#x2192; <code>\"</code> and <code>\</code> &#x2192; <code>\\</code>.
+    <li>Strings should be enclosed in single quotes if they contain any of the following characters: <code>-?:,[]{}#&amp;*!|&gt;"%@`</code>, unless they also contain any single quotes, in which case the string should be enclosed in double quotes instead. This isn't always strictly necessary, but it's better to err on the side of caution. If you really want to only quote strings when absolutely neccessary, be sure to check what you write by copy/pasting the whole data structure the string appears into a YAML parser such as <a href="http://yaml-online-parser.appspot.com/">this one</a> and making sure that what it outputs is correct.
+    <li>Any backslashes or double quotes within a double-quoted string should be escaped with a backslash, ie. <code>"</code> &#x2192; <code>\"</code> and <code>\</code> &#x2192; <code>\\</code>.
     <li>Strings are case-sensitive, apart from file paths, regular expressions and checksums.
 </ul>
-<p>These docs give all example syntax in YAML's least compact representation: you can also use a more compact representation, but it's better for the masterlist to be readable than compact.
+<p>These docs give all example syntax in YAML's least compact representation: you can also use a more compact representation, but make sure that you do not sacrifice readability when doing so.
 <p>Some properties of file paths as used by BOSS:
 <ul>
     <li>They are evaluated as paths relative to the game's Data folder.
@@ -147,7 +149,7 @@ plugins:
 
 
 <h2 id="structs">Data Structures</h2>
-<p>While you could write whatever you wanted in a metadata file without problems, so long as it was valid YAML, it would be pointless as BOSS expects the metadata to be laid out using a certain set of data structures, described in this section.
+<p>BOSS expects metadata to be laid out using a certain set of data structures, described in this section.
 
 <h3 id="structs-tag">Tag Data Structure</h3>
 <p>BOSS metadata files can contain suggestions for the addition or removal of Bash Tags, and this is the structure used for them. It has two forms: the first is a simple string, and the second is a key-value map. All values in the map are strings.
@@ -206,7 +208,7 @@ display: OBSE v18+
     <tbody>
         <tr><td><code>say</code><td>A generic message, useful for miscellaneous notes.
         <tr><td><code>warn</code><td>A warning message, describing a non-critical issue with the user's mods (eg. dirty mods).
-        <tr><td><code>error</code><td>An error message, decribing a critical installation issue (eg. missing masters).
+        <tr><td><code>error</code><td>An error message, decribing a critical installation issue (eg. missing masters, corrupt plugins).
 </table>
 <p>The content data structure is a key-value map, with all values being strings:
 <table>
@@ -260,6 +262,7 @@ would be displayed as
         <tr><td><code>inc</code><td>file list<td>&#x2717;<td>An unordered list of files that this plugin is incompatible with. If any of these files are present, an error message will be displayed.
         <tr><td><code>msg</code><td>message list<td>&#x2717;<td>The messages attached to this plugin. The messages will be displayed in the order that they are listed.
         <tr><td><code>tag</code><td>tag list<td>&#x2717;<td>An unordered list of Bash Tags suggested for this plugin. If a Bash Tag is suggested for both addition and removal, the latter will override the former when the list is evaluated.
+        <tr><td><code>url</code><td>location list<td>&#x2717;<td>An unordered list of location data structures (see below) for this plugin. If the same version can be found at multiple locations, only one location should be recorded. This metadata is not currently used by BOSS.
 </table>
 <p>Example:
 <code class="box">name: "Oscuro's_Oblivion_Overhaul.esm"
@@ -277,6 +280,27 @@ msg:
     content: 'Do not clean. "Dirty" edits are intentional and required for the mod to function.'
 </code>
 
+<h3 id="structs-location">Location Data Structure</h3>
+<p>This data structure is used to hold information on where plugins are hosted online. It is not currently used by BOSS, but it was suggested that since the BOSS team receives a considerable number of plugin URLs, they should be recorded in a standard format, as there is no existing store of such information and it could prove useful in the future.
+<p>The data structure has two forms: the first is a simple string, and the second is a key-value map. The first form should be used for a URL without any associated version data, such as when it is not clear which version is found there, or when it is the only known hosting location for the plugin and as such hosts all available versions. The second form should be used when version data can be associated with the URL, such as when the URL only hosts a subset of the available versions of the plugin.
+<p>The simple form:
+<code class="box"><var>URL</var></code>
+<p>where <code><var>URL</var></code> is a URL at which the plugin may be found.
+<p>The map form:
+<table>
+    <thead><tr><th>Key Name<th>Data Type<th>Required<th>Notes
+    <tbody>
+        <tr><td><code>link</code><td>string<td>&#x2713;<td>A URL at which the plugin may be found.
+        <tr><td><code>ver</code><td>string list<td>&#x2713;<td>A list of versions that can be found at the URL.
+</table>
+<p>Examples:
+<code class="box">http://skyrim.nexusmods.com/mods/19/</code>
+or
+<code class="box">link: http://steamcommunity.com/sharedfiles/filedetails/?id=87144366
+ver: 
+  - 1.3.2c
+</code>
+
 <h2 id="cond">Condition Strings</h2>
 <p>Condition strings can be used to ensure that data is only acted on by BOSS under certain circumstances. They are very similar to boolean conditional expressions in programming languages such as Python, though more limited. Their <a href="https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_Form">EBNF</a> grammar is:
 <code class="box">[ negator ], function, { junctor, [ negator ], function } ;</code>

docs/BOSS Readme.html

@@ -74,10 +74,6 @@ h3{
     <http://www.gnu.org/licenses/>.
 -->
 
-<div id="warning">
-This documentation is a work in progress, covering an application that is also still a work in progress, and is subject to change.
-</div>
-
 <h1>BOSS</h1>
 
 <h2>Contents</h2>
@@ -170,7 +166,8 @@ This documentation is a work in progress, covering an application that is also s
     <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.
+<p>While reading very large plugins, such as the game's main master file, BOSS may appear to stop responding: this is not an issue.
+<p>The time it takes for BOSS to sort your load order depends primarily on the size of the masterlist being used, the total size of the files in your load order, and the number of plugins in your load order. The first run is likely to be longer than subsequent runs as BOSS needs to download the full masterlist, rather than just the changes made by updates. In testing, it was found that sorting ~90 plugins with a total size of ~350 MB and a 5 MB masterlist takes around 15 seconds, though performance will vary with computer hardware.
 
 
 <h3 id="usage-log">The Results Report</h3>
@@ -183,8 +180,8 @@ This documentation is a work in progress, covering an application that is also s
 <p>The report is comprised of three 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.
-    <li>The <q>Graph</q> tab displays a graph of all the interactions between the plugins in your load order. It's not very useful to the average user, but may contain information that would aid in debugging any issues encountered, and is also provided as an item of interest.
+    <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 the plugin's <abbr title="Cyclic Redundancy Check">CRC</abbr> value and extract its version if found in the plugin's description field.
+    <li>The <q>Graph</q> tab displays a graph of all the interactions between the plugins in your load order. It's not very useful to the average user, but may contain information that would aid in debugging any issues encountered, and is also provided as an item of interest. Graph image generation typically takes a long time, so it is disabled by default.
 </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>
@@ -197,8 +194,8 @@ This documentation is a work in progress, covering an application that is also s
     <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.
+<p>BOSS's mod messages are a valuable resource, 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, also report it to an official BOSS thread, so that it can be made conditional.
 
 
 <h3 id="usage-custom">Customising BOSS's Results</h3>
@@ -229,7 +226,7 @@ This documentation is a work in progress, covering an application that is also s
         <tr><td>Incompatibilities<td>This is a list of files that are incompatible with the plugin. BOSS will refuse to sort your load order if any of the listed files are found, and will instead display an error message detailing the problem.
         <p>Any file, not just plugins, can be listed here, and each file has the same three sub-fields as for the requirements field.
         <tr><td>Load After<td>This is a list of plugins which, if present, the current plugin must load after, but which are not required. This field can be used for resolving specific compatibility issues.
-        <tr><td>Messages<td>A list of messages that are to be displayed for the plugin in BOSS's report. These have no bearing on a plugin's position in the load order, but the messages BOSS provides for plugins are one of its most important features.
+        <tr><td>Messages<td>A list of messages that are to be displayed for the plugin in BOSS's report. These have no bearing on a plugin's position in the load order.
         <p>Each message has four sub-fields:
         <ul>
             <li>The <var>type</var> is fairly self-explanatory, and is used to provide messages of varying severity with appropriate emphasis in BOSS's report.
@@ -337,7 +334,7 @@ This documentation is a work in progress, covering an application that is also s
 To translate the BOSS application:
 <ol>
  <li>Download and install the latest version of <a href="http://www.poedit.net/">Poedit</a>.
- <li>Download <a href="">BOSS's translation template file</a>.
+ <li>Download <a href="https://github.com/boss-developers/boss-code/blob/master/resources/l10n/template.pot">BOSS's translation template file</a>.
  <li>If you are updating an existing translation, download the relevant translation file for the language you're interested in:
  <ul>
   <li><a href="">Russian</a>
@@ -387,7 +384,7 @@ To translate the BOSS application:
         <li>Zanderat
     </ul>
 </ul>
-<p>BOSS is written in C/C++ and makes use of <a href="https://subversion.apache.org/">Subversion</a> and the <a href="http://www.davekoelle.com/alphanum.html">Alphanum</a>, <a href="http://www.boost.org/">Boost</a>, <a href="http://github.com/WrinklyNinja/libespm">libespm</a>, <a href="http://github.com/WrinklyNinja/libloadorder">libloadorder</a>, <a href="http://code.google.com/p/pugixml/">PugiXML</a>, <a href="https://code.google.com/p/svgweb/">svgweb</a>, <a href="http://www.wxwidgets.org/">wxWidgets</a> and <a href="http://code.google.com/p/yaml-cpp/">yaml-cpp</a> libraries. BOSS's reports are written in XHTML/CSS/Javascript and make use of <a href="http://github.com/inexorabletash/polyfill">Polyfill.js</a> to provide Internet Explorer 8 compatibility. Copyright license information for all these may be found <a href="licenses/Licenses.txt">here</a>.
+<p>BOSS is written in C/C++ and makes use of <a href="https://subversion.apache.org/">Subversion</a> and the <a href="http://www.davekoelle.com/alphanum.html">Alphanum</a>, <a href="http://www.boost.org/">Boost</a>, <a href="http://github.com/WrinklyNinja/libespm">libespm</a>, <a href="http://github.com/libgit2/libgit2">libgit2</a>, <a href="http://github.com/WrinklyNinja/libloadorder">libloadorder</a>, <a href="http://code.google.com/p/pugixml/">PugiXML</a>, <a href="http://www.wxwidgets.org/">wxWidgets</a> and <a href="http://code.google.com/p/yaml-cpp/">yaml-cpp</a> libraries. BOSS's reports are written in XHTML/CSS/Javascript and make use of <a href="http://github.com/inexorabletash/polyfill">Polyfill.js</a> and <a href="https://code.google.com/p/svgweb/">svgweb</a> to provide Internet Explorer 8 compatibility. Copyright license information for all these may be found <a href="licenses/Licenses.txt">here</a>.
 
 
 <h2 id="project">Project Members</h2>