From 81fc00e0d900a092701260770af7b43e12925ed2 Mon Sep 17 00:00:00 2001 From: Max Paperno Date: Mon, 26 Dec 2022 20:42:23 -0500 Subject: [PATCH] [doc] Edit install/update instructions and site URL in README; Fix referenced Linux install/log paths. --- README.md | 35 +++++++++++++++++++++++------------ doc/pages/Basic.md | 6 +++--- doc/pages/Status.md | 26 +++++++++++++++++++------- 3 files changed, 45 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 91d3ed7..9d45162 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,11 @@ # Dynamic Script Engine Plugin for Touch Portal -![plastic](https://img.shields.io/static/v1?style=flat&labelColor=5884b3&color=black&label=made%20for&message=Touch%20Portal&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA4AAAAOCAYAAAAfSC3RAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAetJREFUeNp0UruqWlEQXUePb1HERi18gShYWVqJYGeXgF+Qzh9IGh8QiOmECIYkpRY21pZWFnZaqWBhUG4KjWih4msys8FLbrhZMOfsx6w1e9beWjAYBOMtx0eOGBEZzuczrtcreAyTyQSz2QxN04j3f3J84vim8+cNR4s3rKfTSUQQi8UQjUYlGYvFAtPpVIQ0u90eZrGvnHLXuOKcB1GpkkqlUCqVEA6HsVqt4HA4EAgEMJvNUC6XMRwOwWTRfhIi3e93WK1W1Go1dbTBYIDj8YhOp4NIJIJGo4FEIoF8Po/JZAKLxQIIUSIUChGrEy9Sr9cjQTKZJJvNRtlsVs3r9Tq53W6Vb+Cy0rQyQtd1OJ1O9b/dbpCTyHoul1O9z+dzGI1Gla7jFUiyGBWPx9FsNpHJZNBqtdDtdlXfAv3vZLmCB6SiJIlJhUIB/X7/cS0viXI8n8+nrBcRIblcLlSrVez3e4jrD6LsK3O8Xi8Vi0ViJ4nVid2kB3a7HY3HY2q325ROp8nv94s5d0XkSsR90OFwoOVySaPRiF6DiHs8nmdXn+QInIxKpaJclWe4Xq9fxGazAQvDYBAKfssDeMeD7zITc1gR/4M8isvlIn2+F3N+cIjMB76j4Ha7fb7bf8H7v5j0hYef/wgwAKl+FUPYXaLjAAAAAElFTkSuQmCC) +[![Made for Touch Portal](https://img.shields.io/static/v1?style=flat&labelColor=5884b3&color=black&label=made%20for&message=Touch%20Portal&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA4AAAAOCAYAAAAfSC3RAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAetJREFUeNp0UruqWlEQXUePb1HERi18gShYWVqJYGeXgF+Qzh9IGh8QiOmECIYkpRY21pZWFnZaqWBhUG4KjWih4msys8FLbrhZMOfsx6w1e9beWjAYBOMtx0eOGBEZzuczrtcreAyTyQSz2QxN04j3f3J84vim8+cNR4s3rKfTSUQQi8UQjUYlGYvFAtPpVIQ0u90eZrGvnHLXuOKcB1GpkkqlUCqVEA6HsVqt4HA4EAgEMJvNUC6XMRwOwWTRfhIi3e93WK1W1Go1dbTBYIDj8YhOp4NIJIJGo4FEIoF8Po/JZAKLxQIIUSIUChGrEy9Sr9cjQTKZJJvNRtlsVs3r9Tq53W6Vb+Cy0rQyQtd1OJ1O9b/dbpCTyHoul1O9z+dzGI1Gla7jFUiyGBWPx9FsNpHJZNBqtdDtdlXfAv3vZLmCB6SiJIlJhUIB/X7/cS0viXI8n8+nrBcRIblcLlSrVez3e4jrD6LsK3O8Xi8Vi0ViJ4nVid2kB3a7HY3HY2q325ROp8nv94s5d0XkSsR90OFwoOVySaPRiF6DiHs8nmdXn+QInIxKpaJclWe4Xq9fxGazAQvDYBAKfssDeMeD7zITc1gR/4M8isvlIn2+F3N+cIjMB76j4Ha7fb7bf8H7v5j0hYef/wgwAKl+FUPYXaLjAAAAAElFTkSuQmCC)](https://www.touch-portal.com) [![GitHub release (latest by date including pre-releases)](https://img.shields.io/github/v/release/mpaperno/DSEP4TP?include_prereleases)](https://github.com/mpaperno/DSEP4TP/releases) ![Supported Platvorms](https://img.shields.io/badge/platforms-windows%20|%20osx%20|%20linux-AA7722) [![GPLv3 License](https://img.shields.io/badge/license-GPLv3-blue.svg)](LICENSE.GPL.txt) - +[![Discord](https://img.shields.io/static/v1?style=flat&color=7289DA&&labelColor=7289DA&message=Discord%20Chat&label=&logo=discord&logoColor=white)](https://discord.gg/FhYsZNFgyw) + **A complete, standalone, multi-threaded JavaScript environment available as a plugin @@ -14,13 +15,13 @@ for use with [Touch Portal](https://www.touch-portal.com/) macro launcher softwa
-**Visit [https://mpaperno.github.io/DSEP4TP/](https://mpaperno.github.io/DSEP4TP/) for all details, including this README.** +**Visit [dse.tpp.max.paperno.us](https://dse.tpp.max.paperno.us) for all details, including this README.**
----------
- +
## Features @@ -59,7 +60,7 @@ global Value or a plugin State and will be replaced by Touch Portal with the act * Send an image to use as a Touch Portal button icon. E.g. with dynamic image name: * `File.read("images/status_icon_${value:MyVariable}.png", 'b').toBase64()` * Get an image from the Internet for a button icon: - * `Net.request("https://mpaperno.github.io/DSEP4TP/images/logo/icon_64.png").get().base64()` + * `Net.request("https://dse.tpp.max.paperno.us/images/logo/icon_64.png").get().base64()` * Read any number of lines from a file, starting from beginning, end, or a specific line number. E.g. read the last 5 lines of a log with a dynamic name: * `` File.readLines(`../logs/console-${new Date().format("yyyyMMdd")}.log`, 5, -1)) `` * Extract a value from a JSON object in a file: @@ -113,17 +114,27 @@ Note: As with all plugins, this requires the Touch Portal Pro (paid) version to just do that and skip to step 5. There is also a [short guide](https://www.touch-portal.com/blog/post/tutorials/import-plugin-guide.php) on the Touch Portal site. 3. Import the plugin: 1. Start/open _Touch Portal_. - 2. Click the "gear" icon at the top and select "Import plugin..." from the menu. + 2. Click the Settings "gear" icon at the top-right and select "Import plugin..." from the menu. 3. Browse to where you downloaded this plugin's `.tpp` file and select it. -4. Restart _Touch Portal_ - * When prompted by _Touch Portal_ to trust the plugin startup script, select "Yes" (the source code is public!). -5. That's it. You should now have the plugin's actions available to you in Touch Portal. + 4. When prompted by _Touch Portal_ to trust the plugin startup script, select "Trust Always" or "Yes" (the source code is public!). + * "Trust Always" will automatically start the plugin each time Touch Portal starts. + * "Yes" will start the plugin this time and then prompt again each time Touch Portal starts. + * If you select "No" then you can still start the plugin manually from Touch Portal's _Settings -> Plug-ins_ dialog. +4. That's it. You should now have the plugin's actions available to you in Touch Portal. + +### Updates + +Unless noted otherwise in the notes of a particular release version, it is OK to just re-install a newer version of the plugin "on top of" +a previous version without uninstalling the old version first. Either way is OK, just keep in mind that uninstalling the plugin via Touch Portal +will also remove any current log files as well. ### Update Notifications -_Watch_ -> _Custom_ -> _Releases_ this repository (button at top) or subscribe to the [ATOM feed](https://github.com/mpaperno/WASimCommander/releases.atom) for release notifications. +In GitHub (with an account) you can _Watch_ -> _Custom_ -> _Releases_ this repository (button at top right). + +Or subscribe to the [ATOM feed](https://github.com/mpaperno/DSEP4TP/releases.atom) for release notifications. -Release announcements are also made in the Touch Portal Discord Server room [#dynamic-script-engine](https://discord.com/channels/548426182698467339/750791488501448887) +Release announcements are also made in the Touch Portal Discord Server room [#dynamic-script-engine](https://discord.gg/FhYsZNFgyw) Or use the provided [example script](@ref example_fetch_and_notify) to check for new versions right from Touch Portal! @@ -132,7 +143,7 @@ Or use the provided [example script](@ref example_fetch_and_notify) to check for ------------- ## Documentation -[Full Documentation & Examples @ https://mpaperno.github.io/DSEP4TP/](https://mpaperno.github.io/DSEP4TP/) - includes this README as well. +[Full Documentation & Examples @ dse.tpp.max.paperno.us](https://dse.tpp.max.paperno.us) - includes this README as well. diff --git a/doc/pages/Basic.md b/doc/pages/Basic.md index 0caf1b0..aec3b4b 100644 --- a/doc/pages/Basic.md +++ b/doc/pages/Basic.md @@ -23,7 +23,7 @@ JavaScript scripts, like a **mini Web browser** or a continuously-running Node.j **An engine instance can persist for the life of the plugin** (that is, it exists as long as the plugin keeps running). * This is an important distinction vs., say, running a Node.js script from a Touch Portal action (using Run an Application or Run a batch file actions, for example). In the latter case the script has no way of saving information (data) between executions (not easily, anyway), plus every time it starts it will need to re-create - it's complete environment, including starting node[.exe] itself and so on. A persistent environment like this plugin provides has no startup "cost" after the initial + it's complete environment, including starting Node itself and so on. A persistent environment like this plugin provides has no startup "cost" after the initial creation, and allows for easily saving data, or "state" (lower case!), between runs. It's more like a Web browser that stays open and can re-run any loaded scripts on demand w/out restarting the whole thing. @@ -62,9 +62,9 @@ So in general the procedure for using any of these results is: this will crate the new State in Touch Portal. 3. Now go back and finish setting up your button/event once the new State has been created and will be available in the various places you can select States from. -Alternately: +Alternately (once you understand the actions described on the next page): 1. Create the Touch Portal State first with a simple JavaScript expression: `TP.stateCreate("dsep.MyNewStateName", "Description of My New State")` -2. Using the ["one-time script"](@ref plugin_actions_one-time-script) actin is perfect for this. +2. Using the ["one-time script"](@ref plugin_actions_one-time-script) action is perfect for this. OK, enough of that, let's get to the Actions! diff --git a/doc/pages/Status.md b/doc/pages/Status.md index f73caac..fd7646c 100644 --- a/doc/pages/Status.md +++ b/doc/pages/Status.md @@ -28,11 +28,11 @@ There is also: ## Logging -The plugin logs operational message to a file. Two, actually. They are both located in your Touch Portal configuration folder, in the 'plugins' subfolder; -the path looks like:
+The plugin logs operational message to a file. Two, actually. They are both located in your Touch Portal configuration folder, in the 'plugins/DSEP4TP' subfolder; +the path looks like this:
* Windows: `C:\Users\\AppData\Roaming\TouchPortal\plugins\DSEP4TP\logs` * Mac: `~/Documents/TouchPortal/plugins/DSEP4TP/logs` -* Linux: `~/TouchPortal/plugins/DSEP4TP/logs` +* Linux: `~/.config/TouchPortal/plugins/DSEP4TP/logs` The two log files are: @@ -52,10 +52,14 @@ You can also "tail" a file using operating system utilities. For example (showin ```ps Get-Content -Tail 10 -Wait $Env:APPDATA\TouchPortal\plugins\DSEP4TP\logs\console.log ``` -- [OS X](https://ss64.com/osx/tail.html) or [Linux](https://ss64.com/bash/tail.html) terminal +- [OS X](https://ss64.com/osx/tail.html) terminal ```shell tail -F -n 10 ~/Documents/TouchPortal/plugins/DSEP4TP/logs/console.log ``` +- [Linux](https://ss64.com/bash/tail.html) terminal + ```shell + tail -F -n 10 ~/.config/TouchPortal/plugins/DSEP4TP/logs/console.log + ``` ### Plugin Log @@ -72,15 +76,23 @@ insidious is going wrong. The logs are rotated daily. The previous days' log is renamed with a date stamp and a new one is started. By default the last 3 days' worth of logs are kept (the current one + 3 historical logs). -You can force a rotation of the logs by going to the plugin's executable directory (`DSEP4TP/bin`) in a terminal/command window and run the plugin (w/out starting it) with the following command:
-* Windows: `DSEP4TP.exe -f1 -j1 -rx` -* Mac/Linux: `./DSEP4TP -f1 -j0 -rx` +You can force a rotation of the logs by going to the plugin's install directory (*) +in a terminal/command window and run the plugin (w/out starting it) with the following command:
+* Windows: `bin/DSEP4TP.exe -f1 -j1 -rx` +* Mac: `./DSEP4TP.app/Contents/MacOS/DSEP4TP -f1 -j0 -rx` +* Linux: `./bin/DSEP4TP -f1 -j0 -rx` * Optionally add a `-k N` switch to the command line to keep `N` number of logs instead of the default 3. Clear out all old logs by using `-k 0` * Use `-h` to see all command-line options. The log files have an "emergency limit" of 1GB in case something goes haywire. If this limit is reached, further logging to that file is disabled until the plugin is restarted. +(*) Plugin install location: +* Windows: `C:\Users\\AppData\Roaming\TouchPortal\plugins\DSEP4TP` +* Mac: `~/Documents/TouchPortal/plugins/DSEP4TP` +* Linux: `~/.config/TouchPortal/plugins/DSEP4TP` + + Read Next: [Scripting Syntax and Caveats](Scripting.md)