diff --git a/README.md b/README.md index d949c3d..f6243e1 100644 --- a/README.md +++ b/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) diff --git a/build.py b/build.py index 711cdaa..6e1ca8b 100644 --- a/build.py +++ b/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("&", "&").replace('"', """).replace("'", "'").replace("<", "<").replace(">", ">") - with open(output_file_bookmark, "w") as out: - out.write("Add Bookmark") - - with open(output_file_copyable, "w") as out: - out.write("Copy to Clipboard") 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: diff --git a/web/index.php b/web/index.php index 091ea99..b8ba51e 100644 --- a/web/index.php +++ b/web/index.php @@ -21,10 +21,11 @@

How to Save History

...in your browser

-

Add the script as a browser bookmark by clicking . Then open Discord and click the bookmark.

+

Add the script as a browser bookmark by clicking ">Add Bookmark. Then open Discord and click the bookmark.

+

In Firefox, make sure to uncheck «Load this bookmark in the sidebar» after clicking Add Bookmark.

...in Discord app

-

Click to copy the script. Then press Ctrl+Shift+I in the Discord app, select Console, paste the script into the text box at the bottom and press Enter to run it. You can then close the console and continue using the script.

+

Click Copy to Clipboard to copy the script. Then press Ctrl+Shift+I in the Discord app, select Console, paste the script into the text box at the bottom and press Enter to run it. You can then close the console and continue using the script.

What next?

When running for the first time, you will see a Settings dialog with additional instructions that explain the limitations and recommendations. Please, read them carefully.