Improve settings descriptions

LogtalkDotOrg · Nov 12, 2024 · 8d4db85 · 8d4db85
1 parent 747c041
commit 8d4db85
Show file tree

Hide file tree

Showing 3 changed files with 23 additions and 15 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,9 @@
 # Changelog
 
+## [0.25.0]
+
+* Improve settings descriptions.
+
 ## [0.24.0]
 
 * Remove edit helper for repeating the last clause head when writing recursive predicates

diff --git a/README.md b/README.md
@@ -212,9 +212,13 @@ Hover contents is provided for built-in directives, built-in predicates, and bui
 
 ## Configuration
 
-The user can configure settings via VSCode menu `Settings`. Entering `Logtalk` in the input box will show up the Logtalk settings. Follows a description of all the settings in this extension with their default values (if any). On Windows, use forward slashes in settings that require paths. Also on Windows, PowerShell 7.3.x or later is required for settings that call scripts. On a POSIX system (e.g. macOS, Linux, or BSD), if you're running Logtalk from a clone of its git repo, you may need to add the `.sh` extension to all scripts in the settings.
+The user can configure settings via VSCode menu `Settings`. Entering `Logtalk` in the input box will show up the Logtalk settings. Follows a description of all the settings in this extension with their default values (if any).
 
-For settings that specify Logtalk scripts, see the script [man pages](https://logtalk.org/documentation.html#man-pages) for their available options.
+On Windows, use forward slashes in settings that require paths. Also on Windows, PowerShell 7.3.x or later is required for settings that call scripts. Use the `where.exe` command to find the absolute path for the required scripts.
+
+On a POSIX system (e.g. macOS, Linux, or BSD), use the `which` command to find the absolute path for the integration and tool scripts. If you're running Logtalk from a clone of its git repo, you may need to add the `.sh` extension to all scripts in the settings.
+
+For settings that specify scripts, see their [man pages](https://logtalk.org/documentation.html#man-pages) for their available options.
 
 ### Logtalk home and user paths
 
@@ -228,7 +232,7 @@ No defaults (VSCode doesn't support using environment variables to define settin
     "logtalk.executable.path": "/usr/local/bin/logtalk"
     "logtalk.executable.arguments": [ ]
 
-Logtalk executable or integration script plus its arguments. On POSIX systems (e.g. macOS, Linux, or BSD), the `logtalk` executable can be created by running the `logtalk_backend_select` script. In alternative, use the integration script you want to use. Absolute paths **must** be used. For example, assuming a POSIX system and using SWI-Prolog as the backend:
+Logtalk executable or integration script plus its arguments. On POSIX systems (e.g. macOS, Linux, or BSD), the `logtalk` executable can be created by running the `logtalk_backend_select` script. In alternative, use the integration script you want to use. Absolute paths **must** be used. For example, assuming a POSIX system, using SWI-Prolog as the backend, with the integration scripts installed at `/usr/local/bin`:
 
     "logtalk.executable.path": "/usr/local/bin/swilgt"
     "logtalk.executable.arguments": [ "-q" ]
@@ -246,7 +250,7 @@ On Windows systems, use the absolute path to the Prolog backend executable **and
     "logtalk.tester.script": "/usr/local/bin/logtalk_tester"
     "logtalk.tester.arguments": [ ]
 
-Automation script for running tests and its arguments. The arguments **must** included at least the `-p` option specifying the Prolog backend. For example, assuming a POSIX system (e.g. macOS, Linux, or BSD) and using SWI-Prolog as the backend:
+Automation script for running tests and its arguments. The arguments **must** included at least the `-p` option specifying the Prolog backend. For example, assuming a POSIX system (e.g. macOS, Linux, or BSD), using SWI-Prolog as the backend, with the integration scripts installed at `/usr/local/bin`:
 
     "logtalk.tester.script": "/usr/local/bin/logtalk_tester"
     "logtalk.tester.arguments": [ "-p", "swi" ]
@@ -263,7 +267,7 @@ On Windows systems, these settings must be set differently. For example (assumin
     "logtalk.doclet.script": "/usr/local/bin/logtalk_doclet"
     "logtalk.doclet.arguments": [ ]
 
-Automation script for running doclets and its arguments. The arguments **must** included at least the `-p` option specifying the Prolog backend. For example, assuming a POSIX system (e.g. macOS, Linux, or BSD) and using SWI-Prolog as the backend:
+Automation script for running doclets and its arguments. The arguments **must** included at least the `-p` option specifying the Prolog backend. For example, assuming a POSIX system (e.g. macOS, Linux, or BSD), using SWI-Prolog as the backend, with the integration scripts installed at `/usr/local/bin`:
 
     "logtalk.doclet.script": "/usr/local/bin/logtalk_doclet"
     "logtalk.doclet.arguments": [ "-p", "swi" ]
@@ -280,7 +284,7 @@ On Windows systems, these settings must be set differently. For example (assumin
     "logtalk.documentation.script": "/usr/local/bin/lgt2html"
     "logtalk.documentation.arguments": [ ]
 
-Documentation script and its arguments for converting the XML files generated by the Logtalk `lgtdoc` tool to their final format. For example, assuming a POSIX system (e.g. macOS, Linux, or BSD):
+Documentation script and its arguments for converting the XML files generated by the Logtalk `lgtdoc` tool to their final format. For example, assuming a POSIX system (e.g. macOS, Linux, or BSD) with the scripts available from `/usr/local/bin`:
 
     "logtalk.documentation.script": "/usr/local/bin/lgt2html"
     "logtalk.documentation.arguments":[ "-t", "APIs documentation" ]
@@ -297,7 +301,7 @@ On Windows systems, these settings must be set differently. For example (assumin
     "logtalk.diagrams.script": "/usr/local/bin/lgt2svg"
     "logtalk.diagrams.arguments": [ ]
 
-Script and its arguments for converting the `.dot` files generated (by default) by the Logtalk `diagrams` tool to their final format (by default, SVG). The default above assumes a POSIX system (e.g. macOS, Linux, or BSD).
+Script and its arguments for converting the `.dot` files generated (by default) by the Logtalk `diagrams` tool to their final format (by default, SVG). The default above assumes a POSIX system (e.g. macOS, Linux, or BSD) with the scripts available from `/usr/local/bin`.
 
 On Windows systems, these settings must be set differently. For example (assuming the default Logtalk installation):
 

diff --git a/package.json b/package.json
@@ -2,7 +2,7 @@
     "name": "logtalk-for-vscode",
     "displayName": "Logtalk for VSCode",
     "description": "Logtalk programming support",
-    "version": "0.24.0",
+    "version": "0.25.0",
     "publisher": "LogtalkDotOrg",
     "icon": "images/logtalk.png",
     "license": "MIT",
@@ -344,17 +344,17 @@
                 },
                 "logtalk.executable.arguments": {
                     "type": "array",
-                    "description": "Arguments of the Logtalk executable or integration script.",
+                    "description": "Arguments of the Logtalk executable or integration script. Optional.",
                     "default": []
                 },
                 "logtalk.tester.script": {
                     "type": "string",
                     "default": "/usr/local/bin/logtalk_tester",
-                    "description": "Automation script for running tests. Must include the backend identifier."
+                    "description": "Automation script for running tests."
                 },
                 "logtalk.tester.arguments": {
                     "type": "array",
-                    "description": "Arguments for the automation script for running tests.",
+                    "description": "Arguments for the automation script for running tests. Must include the backend identifier.",
                     "default": []
                 },
                 "logtalk.doclet.script": {
@@ -370,11 +370,11 @@
                 "logtalk.documentation.script": {
                     "type": "string",
                     "default": "/usr/local/bin/lgt2html",
-                    "description": "Script for converting the XML files generated by the Logtalk lgtdoc tool."
+                    "description": "Script for converting the XML files generated by the Logtalk lgtdoc tool to their final format."
                 },
                 "logtalk.documentation.arguments": {
                     "type": "array",
-                    "description": "Arguments for the script that converts the XML files generated by the Logtalk lgtdoc tool.",
+                    "description": "Arguments for the script that converts the XML files generated by the Logtalk lgtdoc tool. Optional.",
                     "default": []
                 },
                 "logtalk.diagrams.script": {
@@ -384,7 +384,7 @@
                 },
                 "logtalk.diagrams.arguments": {
                     "type": "array",
-                    "description": "Arguments for the script that converts the .dot files generated by the Logtalk diagrams tool.",
+                    "description": "Arguments for the script that converts the .dot files generated by the Logtalk diagrams tool. Optional.",
                     "default": []
                 },
                 "logtalk.scripts.timeout": {
@@ -481,7 +481,7 @@
         "compile": "tsc -watch -p ./",
         "test": "tsc ./tests/runTest.ts",
         "vsix:make": "vsce package --baseImagesUrl https://raw.githubusercontent.com/llvm/llvm-project/master/clang-tools-extra/clangd/clients/clangd-vscode/",
-        "vsix:install": "code --install-extension logtalk-for-vscode-0.24.0.vsix"
+        "vsix:install": "code --install-extension logtalk-for-vscode-0.25.0.vsix"
     },
     "devDependencies": {
         "@types/bluebird": "^3.5.38",