Update build script, readme, and official website

README.md

@@ -1,17 +1,52 @@
-# Usage
+# Welcome
 
-Visit the [official website](https://dht.chylex.com) to add Discord History Tracker (beta) to your bookmarks and download the viewer.
+All you need to **use Discord History Tracker** is either an up-to-date browser, or the [Discord desktop client](https://discordapp.com/download). Visit the [official website](https://dht.chylex.com) for instructions.
 
-# Building
+To **report an issue or suggestion**, first please see the [issues](https://github.com/chylex/Discord-History-Tracker/issues) page and make sure someone else hasn't already created a similar issue report. If you do find an existing issue, comment on it or add a reaction. Otherwise, either click [New Issue](https://github.com/chylex/Discord-History-Tracker/issues/new), or contact me via email [contact@chylex.com](mailto:contact@chylex.com) or Twitter [@chylexmc](https://twitter.com/chylexmc).
 
-The build script requires **Python 3**. For automatic build, run `python build.py`, and a `bld` folder with the track script and viewer will be created.
+If you are interested in **creating your own version** from the source code, continue reading the [build instructions](#Build Instructions) below.
 
-The `track.js` script is ready to be added as a bookmark in a browser, or ran in a browser console. The `track.html` contains a bookmarkable link you can easily include on a website.
+# Build Instructions
 
-## Minification
+Follow the steps below to create your own version of Discord History Tracker.
 
-The build process automatically minifies the generated files. **YUI Compressor** is used for CSS and **UglifyJS** is used for JavaScript. To disable minification, use the `--nominify` flag.
+### Setup
 
-**YUI** requires **Java 7+** on the PATH. If Java is not available, CSS compression will be skipped.
+Fork the repository and clone it to your computer (if you've never used git, you can download the [GitHub Desktop](https://desktop.github.com) client to get started quickly).
 
-**UglifyJS** is executed using the included **Node** runner with all required packages already installed in the repository. The runner requires 64-bit Windows; to run builds with JS minification on a different system, either add `uglify-es` into the global namespace via `npm install uglify-es -g`, or download the appropriate [Node binaries](https://nodejs.org/en/download/) and modify the build script.
+Now you can modify the source code:
+* `src/tracker/` contains JS files that are automatically combined into the **tracker bookmark/script**
+* `src/renderer/` contains HTML, CSS, JS files that are then combined into the **offline viewer page**
+* `lib/` contains utilities required to build the project
+* `web/` contains source code of the [official website](https://dht.chylex.com), which can be used as a template when making your own website
+
+### Building
+
+After you've done changes to the source code, you will need to build it. Before that, download and install:
+* (**required**) [Python 3](https://www.python.org/downloads)
+  * Use to run the build script
+* (optional) [Java 7+](https://www.java.com/inc/BrowserRedirect1.jsp) / [OpenJDK 7+](http://openjdk.java.net/install/index.html)
+  * Only required for optional [CSS minification](#Minification)
+* (optional) [Node + npm](https://nodejs.org/en) & command line [uglify-es](https://www.npmjs.com/package/uglify-es)
+  * Not required on Windows
+  * Only required for optional [JS minification](#Minification) on Linux/Mac
+
+Now open the folder that contains `build.py` in a command line, and run `python build.py` to create a build with default settings. The following files will be created:
+* `bld/track.js` is the raw tracker script that can be pasted into a browser console
+* `bld/track.html` is the tracker script but sanitized for inclusion in HTML (see `web/index.php` for examples)
+* `bld/viewer.html` is the complete offline viewer
+
+You can tweak the build process using the following flags:
+* `python build.py --nominify` to disable [minification](#Minification)
+
+### Minification
+
+The build process automatically minifies the CSS using `YUI Compressor` and JS files using `UglifyJS@3`.
+
+* If the `--nominify` flag is used, minification will be completely disabled
+* If Java is not available from the command line, CSS minification will be skipped
+  * You can check whether you have installed Java correctly by running `java -version` in the command line, and making sure the version is `1.7.xyz` or higher
+* If `uglify-es` is not available from the command line, JS minification will be skipped
+  * When building on Windows 64-bit, the build script will use the included Node runner and packages
+  * When building on Windows 32-bit, you will need to download [Node 32-bit](https://nodejs.org/en/download) and replace the included one in `lib/`
+  * When building on Linux/Mac, the build script will attempt to find `uglifyjs` in the command line, however you need to make sure it's the correct package (only `uglify-es` will work; if you install the older package just named `uglifyjs`, then it will crash and probably set something on fire)

build.py

@@ -46,8 +46,7 @@ def combine_files(input_pattern, output_file):
 
 def build_tracker():
   output_file_raw = "bld/track.js"
-  output_file_bookmark = "bld/track_bookmark.html"
-  output_file_copyable = "bld/track_copyable.html"
+  output_file_html = "bld/track.html"
   
   output_file_tmp = "bld/track.tmp.js"
   input_pattern = "src/tracker/*.js"
@@ -77,15 +76,8 @@ def build_tracker():
   with open(output_file_raw, "r") as raw:
     script_contents = raw.read().replace("&", "&amp;").replace('"', "&quot;").replace("'", "&#x27;").replace("<", "&lt;").replace(">", "&gt;")
   
-  with open(output_file_bookmark, "w") as out:
-    out.write("<a rel='sidebar' title='Discord History Tracker' href='")
+  with open(output_file_html, "w") as out:
     out.write(script_contents)
-    out.write("'>Add Bookmark</a>")
-  
-  with open(output_file_copyable, "w") as out:
-    out.write("<a href='javascript:' id='tracker-copy'>Copy to Clipboard</a><textarea id='tracker-copy-contents'>")
-    out.write(script_contents)
-    out.write("</textarea>")
 
 
 def build_renderer():
@@ -142,16 +134,14 @@ def build_renderer():
 
 
 def build_website():
-  tracker_file_bookmark = "bld/track_bookmark.html"
-  tracker_file_copyable = "bld/track_copyable.html"
+  tracker_file_html = "bld/track.html"
   viewer_file = "bld/viewer.html"
   web_style_file = "bld/web/style.css"
   
   distutils.dir_util.copy_tree("web", "bld/web")
   
   os.makedirs("bld/web/build", exist_ok = True)
-  shutil.copyfile(tracker_file_bookmark, "bld/web/build/track_bookmark.html")
-  shutil.copyfile(tracker_file_copyable, "bld/web/build/track_copyable.html")
+  shutil.copyfile(tracker_file_html, "bld/web/build/track.html")
   shutil.copyfile(viewer_file, "bld/web/build/viewer.html")
   
   if USE_JAVA:

web/index.php

@@ -21,10 +21,11 @@
       
       <h2>How to Save History</h2>
       <h3>...in your browser</h3>
-      <p>Add the script as a browser bookmark by clicking <?php include "./build/track_bookmark.html"; ?>. Then open <a href="https://discordapp.com/channels/@me">Discord</a> and click the bookmark.</p>
+      <p>Add the script as a browser bookmark by clicking <a rel="sidebar" title="Discord History Tracker" href="<?php include "./build/track.html"; ?>">Add Bookmark</a>. Then open <a href="https://discordapp.com/channels/@me">Discord</a> and click the bookmark.</p>
+      <p>In Firefox, make sure to uncheck &laquo;Load this bookmark in the sidebar&raquo; after clicking <strong>Add Bookmark</strong>.</p>
       
       <h3>...in Discord app</h3>
-      <p>Click <?php include "./build/track_copyable.html"; ?> to copy the script. Then press <strong>Ctrl+Shift+I</strong> in the Discord app, select <strong>Console</strong>, paste the script into the text box at the bottom and press <strong>Enter</strong> to run it. You can then close the console and continue using the script.</p>
+      <p>Click <a href="javascript:" id="tracker-copy">Copy to Clipboard</a><textarea id="tracker-copy-contents"><?php include "./build/track.html"; ?></textarea> to copy the script. Then press <strong>Ctrl+Shift+I</strong> in the Discord app, select <strong>Console</strong>, paste the script into the text box at the bottom and press <strong>Enter</strong> to run it. You can then close the console and continue using the script.</p>
       
       <h3>What next?</h3>
       <p>When running for the first time, you will see a <strong>Settings</strong> dialog with additional instructions that explain the limitations and recommendations. Please, read them carefully.</p>