Improve documentation, add debugging docs

.github/ISSUE_TEMPLATE/bug-report--non-formatter-.md

@@ -8,7 +8,7 @@ labels: bug
 assignees: mark-wiemer
 ---
 
-For troubleshooting assistance, refer to the [troubleshooting guide](https://github.com/mark-wiemer/ahkpp/blob/main/docs/Troubleshooting.md)
+For troubleshooting assistance, refer to the [troubleshooting guide](https://github.com/mark-wiemer/ahkpp/blob/main/docs/troubleshooting.md)
 
 ## Description
 

changelog.md

@@ -20,7 +20,7 @@
 
 ### Fixes
 
--   Add [troubleshooting guide](docs/Troubleshooting.md)
+-   Add [troubleshooting guide](docs/troubleshooting.md)
 -   Fix go to definition in AHK v1 files ([#559](https://github.com/mark-wiemer/ahkpp/issues/559))
 -   Remove unnecessary error message "Couldn't resolve AHK v2 interpreter" ([#493](https://github.com/mark-wiemer/ahkpp/issues/493))
     -   This has been moved to a output log visible in the AHK++ (v2) output channel
@@ -156,7 +156,7 @@ More changes are listed below the breaking changes...
 
 ### ⛓️‍💥 Breaking changes
 
-Settings are now organized into flat objects for a better user experience. Unfortunately, this means settings will have to be replaced when upgrading to AHK++ 6. This is a one-time fixup. Below are sample settings matching the new schema and default values of AHK++. You can learn more about the settings via VS Code's settings UI (`Ctrl + ,`)
+Settings are now organized into flat objects for a better user experience. Unfortunately, this means settings will have to be replaced when upgrading to AHK++ 6. This is a one-time fixup. Below are sample settings matching the new schema and default values of AHK++. You can learn more about the settings via VS Code's settings UI (`Ctrl+,`)
 
 <details open><summary>Default AHK++ settings</summary>
 
@@ -255,10 +255,10 @@ Settings are now organized into flat objects for a better user experience. Unfor
 ### New commands
 
 -   Debug AHK and Attach: Debug and attach to the debug session for advanced use-cases. Requires zero-plusplus.vscode-autohotkey-debug.
--   Debug AHK with Params (`Ctrl + F5`): Debug and add user-provided command-line arguments to the debugger for advanced use-cases. Requires zero-plusplus.vscode-autohotkey-debug.
+-   Debug AHK with Params (`Ctrl+F5`): Debug and add user-provided command-line arguments to the debugger for advanced use-cases. Requires zero-plusplus.vscode-autohotkey-debug.
 -   Run AHK++ Diagnostic: Effectively restart the AHK v2 features of the app.
 -   Export AHK Symbols: Export application functions and classes to a new file. Only for AHK v2.
--   Stop AHK Script (`Ctrl + F6`): Stop an AHK script of user choice ran via `Run AHK Script` or any of the `Debug AHK ...` commands. If only one script is running, stop that without asking for confirmation.
+-   Stop AHK Script (`Ctrl+F6`): Stop an AHK script of user choice ran via `Run AHK Script` or any of the `Debug AHK ...` commands. If only one script is running, stop that without asking for confirmation.
 -   Add Doc Comment: Add a function header comment for the current function. Only for AHK v2.
 -   Update File Version Info: Add or update a file header comment
 -   Switch AHK Version: Change between AHK v1 and v2 for the current file
@@ -279,7 +279,7 @@ Settings are now organized into flat objects for a better user experience. Unfor
 -   Add recommended VS Code extensions for working in this codebase
 -   Simplify launch configurations
 -   Improve manual tests and add manual tests for new AHK v2 capabilities
--   Add [full v2 integration docs](docs/FullV2Integration.md)
+-   Add [full v2 integration docs](docs/full-v2-integration.md)
 -   Clarify [license](license.md): even more open-source than before!
 
 ### 💚 Thank you!
@@ -360,7 +360,7 @@ For [technical reasons](https://code.visualstudio.com/api/working-with-extension
 -   Add full v2 support via [thqby's AutoHotkey v2 Language Support](https://marketplace.visualstudio.com/items?itemName=thqby.vscode-autohotkey2-lsp)
     -   No need to install that extension, all features are bundled into this extension
     -   Future work will de-dupe commands like "debug", "run selection", and "open help"
-    -   Known issues and all new features are documented at [full v2 integration](docs/FullV2Integration.md)
+    -   Known issues and all new features are documented at [full v2 integration](docs/full-v2-integration.md)
 
 </details>
 
@@ -429,7 +429,7 @@ Be sure to go to the settings and update the new `V2` settings in case the defau
         1. "AutoHotkey v1"
 -   Automatically change AHK version to match the `#Requires` directive near the top of any script the first time that script is opened
 -   Allow running and debugging v1 or v2 scripts without changing settings
--   "Open help" (Ctrl + F1) now opens version-specific help
+-   "Open help" (Ctrl+F1) now opens version-specific help
 -   Add full syntax highlighting for v2 scripts thanks to [AutoHotkey v2 Language Support by thqby](https://marketplace.visualstudio.com/items?itemName=thqby.vscode-autohotkey2-lsp)
 -   Update icons (found next to a script's name in the explorer)
     -   v2 scripts will have official green icons, while v1 scripts now have modified blue icons
@@ -498,7 +498,7 @@ Fixes:
 
 ## 3.2.0 - 2023-01-29 ❄️
 
--   Debug keyboard shortcut is now `Ctrl + Alt + F9` (was `F9`) to avoid conflicts with VS Code default shortcuts.
+-   Debug keyboard shortcut is now `Ctrl+Alt+F9` (was `F9`) to avoid conflicts with VS Code default shortcuts.
 -   New setting: Snippet template name. Create your own template for new AHK files, including no template at all.
 -   [Moving lines of code via commands](https://code.visualstudio.com/docs/getstarted/keybindings#_basic-editing) now (almost) correctly indents ([PR #306](https://github.com/mark-wiemer/ahkpp/pull/306), issue [#319](https://github.com/mark-wiemer/ahkpp/issues/319))
 -   Snippets and keywords updated to AutoHotkey v1.1.36.0 ([PR #288](https://github.com/mark-wiemer/ahkpp/pull/288), [PR #298](https://github.com/mark-wiemer/ahkpp/pull/298))

docs/_welcome.md

@@ -0,0 +1,15 @@
+# Welcome to AHK++
+
+This folder serves as documentation for the various features of AHK++, both for users and contributors.
+
+| File                                               | Description                                          |
+| -------------------------------------------------- | ---------------------------------------------------- |
+| [debugging.md](./debugging.md)                     | Debug AHK scripts                                    |
+| [development.md](./development.md)                 | Development process for contributors                 |
+| [features.md](./features.md)                       | Comprehensive list of features                       |
+| [full-v2-integration.md](./full-v2-integration.md) | Updates from September 2024 AHK v2 support (AHK++ 6) |
+| [install-from-vsix.md](./install-from-vsix.md)     | Install a local version of AHK++ on an IDE           |
+| [localization.md](./localization.md)               | Translate AHK++ to other languages                   |
+| [settings.md](./settings.md)                       | Comprehensive list of settings                       |
+| [template-snippet.md](./template-snippet.md)       | About the snippet that appears for new AHK files     |
+| [troubleshooting.md](./troubleshooting.md)         | Resolve issues with AHK++                            |

docs/debugging.md

@@ -0,0 +1,44 @@
+# Debugging
+
+You can use AHK++ as a [debugger](https://en.wikipedia.org/wiki/Debugger) for AHK scripts.
+
+## Via keyboard shortcut
+
+When an AHK file is open, press `Ctrl+Alt+F9` to start debugging.
+
+## Via title bar
+
+AHK++ adds run and debug buttons to the editor's title bar whenever an AHK file is opened.
+
+1. Open an AHK file
+1. Find the run button near the top right of the editor
+1. Click the dropdown alt of the run button
+1. Click "Debug AHK Script"
+
+![](../image/debugTitleBar.png)
+
+## Via launch.json
+
+VS Code supports debug configurations definitions in `.vscode/launch.json`. This can be a useful way to run your `main.ahk` script from wherever you are in your workspace with a single keystroke.
+
+⚠️ There are some known issues with AHK++ support for debug configurations, refer to [#603](https://github.com/mark-wiemer/ahkpp/issues/603) for details.
+
+1. Create `.vscode/launch.json` in your workspace
+1. Populate it with whatever launch config you prefer, for example:
+
+    ```jsonc
+    {
+        "version": "0.2.0",
+        "configurations": [
+            {
+                "type": "ahk", // or ahk2
+                "request": "launch",
+                "name": "AutoHotkey debugger",
+                "program": "${workspaceFolder}\\main.ahk1", // requires backslashes for now
+                "stopOnEntry": true,
+            },
+        ],
+    }
+    ```
+
+1. Press `F5` to debug your project

docs/Development.md → docs/development.md

@@ -54,7 +54,7 @@ Unless otherwise specified, commit messages don't matter.
         1. Attach binary
         1. Publish release
 
-When the tag is pushed, changes will automatically be published.
+When the tag is pushed, changes will automatically be published by the [deploy workflow](https://github.com/mark-wiemer/ahkpp/actions/workflows/deploy.yml).
 
 ### Validating deployment
 

docs/FullV2Integration.md → docs/full-v2-integration.md

@@ -24,7 +24,7 @@ This doc covers all the new features as a result of integrating with thqby's AHK
 -   Switch AHK Version (`ahk++.switchAhkVersion`): Change between AHK v1 and v2 for the current file
 -   Select AHK Syntaxes (`ahk++.selectSyntaxes`): Select custom AHK v2 syntax files for advanced use-cases. PRs are welcomed if the default syntaxes aren't sufficient!
 -   Set A_ScriptDir Here (`ahk++.setAScriptDir`): Set [`A_ScriptDir`](https://www.autohotkey.com/docs/v2/Variables.htm#ScriptDir) to the path of the current file. Only for AHK v2.
--   Set AHK v2 Interpreter (`ahk++.setV2Interpreter`): Open a quick pick to change the AHK v2 intepreter for all scripts.
+-   Set AHK v2 Interpreter (`ahk++.setV2Interpreter`): Open a quick pick to change the AHK v2 interpreter for all scripts.
 
 ### New settings
 
@@ -33,7 +33,7 @@ All new settings are in the `V2` settings category
 -   Action When V1 Detected: Action when v1 script is detected
 -   Library Suggestions: Whether to suggest functions included in library files
 -   Comment Tag Regex: The regular expression for custom symbols to appear in the breadcrumb and elsewhere. Default matches any line that starts with `;;`
--   Complete Function Calls: Whether to automatically add parenetheses when calling a function
+-   Complete Function Calls: Whether to automatically add parentheses when calling a function
 -   Completion Commit Characters: Characters which commit auto-completion
 -   Debug Configuration: The [launch configuration](https://code.visualstudio.com/docs/editor/debugging#_launch-configurations) to use when debugging
 -   Diagnostics

docs/settings.md

@@ -1,4 +1,4 @@
-# AHK++ settings
+# Settings
 
 AHK++ has a lot of configuration options, and they can be hard to understand
 within VS Code's default settings editor. This page covers every setting in
@@ -29,7 +29,7 @@ All settings, alphabetically by section ID:
 | v1: File                         | compileBaseFile               | path                                                   | (empty string)                                      | Base file path for compiling v1 scripts (optional).                                                                                                                                                                                                                    |
 | v1: File                         | helpPath                      | path                                                   | C:/Program Files/AutoHotkey/AutoHotkey.chm          | Path to the AHK v1 help document.                                                                                                                                                                                                                                      |
 | v1: File                         | interpreterPath               | path                                                   | C:/Program Files/AutoHotkey/AutoHotkeyU64.exe       | Path to the AHK v1 interpreter.                                                                                                                                                                                                                                        |
-| v1: File                         | templateSnippetName           | string                                                 | AhkTemplateV1                                       | The name of the [template snippet](./TemplateSnippet.md) to populate new AHK v1 files. If blank, no snippet will be applied.                                                                                                                                           |
+| v1: File                         | templateSnippetName           | string                                                 | AhkTemplateV1                                       | The name of the [template snippet](./template-snippet.md) to populate new AHK v1 files. If blank, no snippet will be applied.                                                                                                                                          |
 | v1: Formatter                    | allowedNumberOfEmptyLines     | number                                                 | 1                                                   | Allowed number of empty lines. <ul><li>-1: Ignore empty lines.</li><li>0: No empty lines.</li></ul>                                                                                                                                                                    |
 | v1: Formatter                    | indentCodeAfterIfDirective    | boolean                                                | true                                                | Indent code after a directive that creates context-sensitive hotkeys or hotstrings (`#If`, `#IfWinActive`, `#IfWinNotActive`, `#IfWinExist`, `#IfWinNotExist`).                                                                                                        |
 | v1: Formatter                    | indentCodeAfterLabel          | boolean                                                | true                                                | Indent code after hotkeys and labels in top-level code blocks.                                                                                                                                                                                                         |

package.nls.json

@@ -20,7 +20,7 @@
     "ahk++.config.general.showOutput.always": "Always open the output view when running a script",
     "ahk++.config.general.showOutput.never": "Never automatically show the output view",
     "ahk++.config.menu.showDebugButton": "Show the debug buttons in the editor title menu.",
-    "ahk++.config.v1.file": "[Learn more about the template snippet](https://github.com/mark-wiemer/ahkpp/tree/main/docs/TemplateSnippet.md)",
+    "ahk++.config.v1.file": "[Learn more about the template snippet](https://github.com/mark-wiemer/ahkpp/tree/main/docs/template-snippet.md)",
     "ahk++.config.v1.file.compileBaseFile": "Base file path for compiling v1 scripts (optional).",
     "ahk++.config.v1.file.helpPath": "Path to the AHK v1 help document.",
     "ahk++.config.v1.file.interpreterPath": "Path to the AHK v1 interpreter.",

package.nls.zh-cn.json

@@ -23,7 +23,7 @@
     "ahk++.config.general.showOutput.always": "运行脚本时始终打开输出视图",
     "ahk++.config.general.showOutput.never": "从不自动显示输出视图",
     "ahk++.config.menu.showDebugButton": "在编辑器标题菜单中显示调试按钮。",
-    "ahk++.config.v1.file": "[了解有关模板片段的更多信息](https://github.com/mark-wiemer/ahkpp/tree/main/docs/TemplateSnippet.md)",
+    "ahk++.config.v1.file": "[了解有关模板片段的更多信息](https://github.com/mark-wiemer/ahkpp/tree/main/docs/template-snippet.md)",
     "ahk++.config.v1.file.compileBaseFile": "用于编译 v1 脚本的基本文件路径（可选）。",
     "ahk++.config.v1.file.helpPath": "AHK v1 帮助文档的路径。",
     "ahk++.config.v1.file.interpreterPath": "AHK v1 解释器的路径。",

readme.md

@@ -8,7 +8,7 @@
     <div>Quick help</div>
     <div>...and more</div>
     <br />
-    <div><a href="docs/Troubleshooting.md">Troubleshooting</a> | <a href="https://github.com/mark-wiemer/ahkpp/issues/new/choose">Open a bug</a> | <a href="https://marketplace.visualstudio.com/items?itemName=mark-wiemer.vscode-autohotkey-plus-plus&ssr=false#review-details">Leave a review</a></div>
+    <div><a href="docs/troubleshooting.md">Troubleshooting</a> | <a href="https://github.com/mark-wiemer/ahkpp/issues/new/choose">Open a bug</a> | <a href="https://marketplace.visualstudio.com/items?itemName=mark-wiemer.vscode-autohotkey-plus-plus&ssr=false#review-details">Leave a review</a></div>
 </div>
 
 ## Install
@@ -23,7 +23,7 @@ AHK++ 6 incorporates [AutoHotkey v2 Language Support by thqby](https://marketpla
 
 -   Running, debugging, and stopping v1 and v2 scripts without changing settings
 -   Full syntax highlighting for v2 scripts
--   "Open help" (`Ctrl + F1`) opens language-specific help (and includes your text selection)
+-   "Open help" (`Ctrl+F1`) opens language-specific help (and includes your text selection)
 -   Unique icons for AHK v1 (blue) and v2 (green)
 -   Rich IntelliSense support with snippets, hover text, and suggestions
 -   Formatting files with many customized options
@@ -40,18 +40,18 @@ As always, please [🐛 report any issues](https://github.com/mark-wiemer/ahkpp/
 
 With AHK++, you can compile, debug, and run your scripts with keyboard shortcuts. You can also run a selection as a standalone script.
 
--   Compile: `Ctrl + Shift + F9`
--   Debug: `Ctrl + Alt + F9`
--   Open help: `Ctrl + F1`
--   Run: `Ctrl + F9`
--   Run selection: `Ctrl + F8`
--   Stop: `Ctrl + F6`
+-   Compile: `Ctrl+Shift+F9`
+-   Debug: `Ctrl+Alt+F9`
+-   Open help: `Ctrl+F1`
+-   Run: `Ctrl+F9`
+-   Run selection: `Ctrl+F8`
+-   Stop: `Ctrl+F6`
 
 ## Debug
 
 > There are some [known issues with the debugger](https://github.com/mark-wiemer/ahkpp/issues?q=is%3Aopen+is%3Aissue+label%3Adebugger). If you need an advanced setup, we recommend [zero-plusplus.vscode-autohotkey-debug](https://marketplace.visualstudio.com/items?itemName=zero-plusplus.vscode-autohotkey-debug) for now. Please [open an issue](https://github.com/mark-wiemer/ahkpp/issues/new/choose) if the built-in debugger does not support your needs. As `zero-plusplus.vscode-autohotkey-debug` is [closed-source](https://github.com/zero-plusplus/vscode-autohotkey-debug/discussions/332), we will be working to introduce advanced debugger features to ensure an open-source, collaborative, complete extension is available to the AHK community 🙂
 
-1. Click the debug button in the editor title menu (at the top right of the editor) or press `Ctrl + Alt + F9`.
+1. Click the debug button in the editor title menu (at the top right of the editor) or press `Ctrl+Alt+F9`.
 2. The debugger supports breakpoints, stack tracing, and variable watching
 
     ![Debug](image/debug.gif)
@@ -82,7 +82,7 @@ This extension provides basic debugging functions. If you need more debugging fu
 Select a symbol, then:
 
 -   Right-click and select `Find All References`.
--   Or press `Shift + F12`.
+-   Or press `Shift+F12`.
 
 ### Hover tip