diff --git a/README-WINDOWS.md b/README-WINDOWS.md index 7aba4fd70..813509a0b 100644 --- a/README-WINDOWS.md +++ b/README-WINDOWS.md @@ -6,98 +6,184 @@ [TTRPG-Convert-CLI 5e]: https://obsidianttrpgtutorials.com/Obsidian+TTRPG+Tutorials/Plugin+Tutorials/TTRPG-Convert-CLI/TTRPG-Convert-CLI+5e [TTRPG-Convert-CLI PF2e]: https://obsidianttrpgtutorials.com/Obsidian+TTRPG+Tutorials/Plugin+Tutorials/TTRPG-Convert-CLI/TTRPG-Convert-CLI+PF2e -We're going to assume a user named `Xanathar` in this guide. +## Requirements +- [Git][] is recommended to easily download and update the JSON sources +- Existing experience with using a command line isn't required, but may be useful. These instructions should be + sufficient, but you can look at the following resources for additional background on how to use the Windows + command line: + - [A Beginner's Guide to the Windows Command Line](https://www.makeuseof.com/tag/a-beginners-guide-to-the-windows-command-line/) + - [How to Open Command Prompt in a Folder](https://www.lifewire.com/open-command-prompt-in-a-folder-5185505) -- When you use the example commands, replace `Xanathar` with your user name. +## Instructions -## How the Windows command prompt works - -You can Open the Windows command prompt by pressing the Windows key and entering `cmd`. - -- The text to the left of the cursor (e.g. `C:\Users\Xanathar`) is your current directory. - -- To navigate elsewhere, use the `cd` command to "change directory". - For example, to get to your `Downloads` folder from here, type `cd Downloads` and hit `Enter`. - The prompt on the left should now say `C:\Users\Xanathar\Downloads`. - -- To see the folders you can reach this way, type `dir` and hit `Enter`. - You'll be presented with a table, the rightmost column listing all of the folder contained by the active folder. - -## Downloading materials - -This is one example with specific steps. If you know more about running commands on Windows, feel free to go your own way. +> [!TIP] +> There are actually three(ish) different kinds of command line programs on Windows. Command Prompt, PowerShell +> and Terminal. For our purposes they're mostly interchangeable, but the default program is different +> depending on what version of Windows you have, so if you see e.g. "PowerShell" mentioned, but you have +> "Command Prompt", don't worry - they should all work the same for the instructions here. 1. From the [latest release][1], download the following files: - `ttrpg-convert-cli-2.3.16-windows-x86_64.zip` - `ttrpg-convert-cli-2.3.16-examples.zip` -2. Unzip the downloaded files and make sure the folder structure doesn't contain duplicated/nested folders - - You want `ttrpg-convert-cli-2.3.16` to contain bin, LICENSE, and README.md, not another folder called `ttrpg-convert-cli-2.3.16`. - -3. Put the `ttrpg-convert-cli-2.3.16` folder in any place you like. +2. Unzip the downloaded files into a place you'll remember. For example, `Downloads`. +3. Navigate to the `bin` directory inside the unzipped files. It might be nested within another folder. You should see a `ttrpg-convert` EXE file in the folder - see the screenshot below. +4. In Explorer, hold **Shift** and **Right Click** within the folder (not on any particular file). Select + *Open in Terminal* (this may also be *Open PowerShell window here*, or *Open command window here* if you + have an older version of Windows) - For this example, you'll be working from within the bin folder, which contains the file `ttrpg-convert.exe`. + ![A screenshot of Windows Explorer showing a "ttrpg-convert.exe" file There is a right-click context menu with the "Open PowerShell window here" option highlighted](docs/screenshots/windows-explorer-folder-context-menu.png) +5. A new window should open up, showing something like this. The path to the left of the cursor should match + wherever you extracted the files to: - 1. Move the other two folders you extracted (`5etools-mirror-2.github.io-master` and `ttrpg-convert-cli-2.3.16-examples`) inside of the bin directory. + ![A screenshot of a Windows Powershell window opened to the ttrpg-convert-cli directory](docs/screenshots/windows-powershell-open.png) - 2. If you leave the extracted `ttrpg-convert-cli-2.3.16` folder in the Downloads directory, the following commands should work: - - 1. Make the `Downloads` directory active. When you list the folders, it should include `ttrpg-convert-cli-2.3.16`. - - ```console - cd C:\Users\Xanathar\Downloads - dir - ``` - - 2. Make the `ttrpg-convert-cli` active. When you list the folders, it should include `bin`. - - ```console - cd ttrpg-convert-cli-2.3.16 - dir - ``` - - 3. Make the `bin` active. When you list the folders, it should include `5etools-mirror-2.github.io-master` and `ttrpg-convert-cli-2.3.16-examples`. - - ```console - cd bin - dir - ``` - -[1]: https://github.com/ebullient/ttrpg-convert-cli/releases/latest - -## Running the CLI - -1. Open Command Prompt. - -2. Navigate to the bin folder. - - - If you followed the example above, you can do: `cd C:\Users\Xanathar\Downloads\ttrpg-convert-cli-2.3.16\bin` - - Alternately, navigate to the `ttrpg-convert-cli-2.3.16` folder in File Explorer and copy the path from the address bar. - Then go back to Command Prompt, type `cd` and paste the path you just copied, and hit `Enter`. - The prompt on the left should now look like this: `\ttrpg-convert-cli-2.3.16\bin` - -3. Type `ttrpg-convert.exe --index -o dm 5etools-mirror-2.github.io-master/data` and hit `Enter`. - - A new folder called `dm` should have been created containing the entire D&D5e SRD. If that's all you need, you're done. - -4. If you want to add additional sources, templates, or books, [create a config file][3]. - - - Use this command to use your custom configuration (assuming a file called `dm-sources.json`): - - ```console - ttrpg-convert.exe --index -o dm -c dm-sources.json 5etools-mirror-2.github.io-master/data +6. Acquire the JSON data sources following the instructions in [Convert 5eTools JSON data][] or [Convert Pf2eTools JSON data][] by entering commands in this window and pressing **Enter**. + - For example, for 5eTools, run the following command (assuming that you have [Git][] installed): + ``` + git clone --depth 1 https://github.com/5etools-mirror-2/5etools-mirror-2.github.io.git + ``` + - Or, for Pf2eTools: + ``` + git clone --depth 1 https://github.com/Pf2eToolsOrg/Pf2eTools.git ``` + - If you don't have Git, you can instead manually download the latest [5eTools release](https://github.com/Pf2eToolsOrg/Pf2eTools/releases/latest) or [Pf2eTools release](https://github.com/Pf2eToolsOrg/Pf2eTools/releases/latest) and extract the zip file to the `bin/` directory, so that it sits alongside the `ttrpg-convert.exe` file. + - At this point, it should look like this: + + ![A screenshot of a Windows Explorer window with a ttrpg-convert.exe file next to a 5etools-mirror-2.github.io folder, and a Powershell window showing the output of the git command to download the sources](docs/screenshots/windows-explorer-powershell-with-sources.png) + +7. Run the tool to check that it works. Enter `./ttrpg-convert --version` following into the terminal and press Enter + to run the command. You should see something like the following: + ``` + PS C:\Users\Kelly\Downloads\ttrpg-convert-cli-2.3.14-windows-x86_64\bin> .\ttrpg-convert --version + ttrpg-convert version 2.3.14 + Git commit: 6ecb310 + Build time: 2024-05-18T12:36:51Z + ``` + If this works, then you're good to run the command to generate your notes. Otherwise, look below + for troubleshooting instructions +8. Run the tool to generate your notes. What this looks like depends on what you want the tool to do + and is described more in detail elsewhere in the README. For example, to generate notes from the + D&D5e SRD into a folder called `dm`, run: + ``` + ./ttrpg-convert --index -o dm 5etools-mirror-2.github.io-master/data + ``` + - You should see output like the following, listing out how many notes of each type were generated, and a new `dm` folder should be in that directory. + + ![A screenshot of a Windows Explorer window with a ttrpg-convert.exe file next to a 5etools-mirror-2.github.io folder and a dm folder, and a Powershell window showing the output of the ttrpg-convert command](docs/screenshots/windows-explorer-powershell-after-run.png) +9. To use additional sources, templates, or books, or for more configuration options, + [create a config file][3] and [see the main README][4]. + + - For example, assuming you have a custom configuration located in a file called `dm-sources.json`, you can + use this command to generate notes using that configuration: + ``` + ./ttrpg-convert --index -o dm -c dm-sources.json 5etools-mirror-2.github.io-master/data + ``` + +[Convert 5eTools JSON data]: https://github.com/ebullient/ttrpg-convert-cli/tree/main?tab=readme-ov-file#convert-5etools-json-data +[Convert Pf2eTools JSON data]: https://github.com/ebullient/ttrpg-convert-cli/tree/main?tab=readme-ov-file#convert-pf2etools-json-data +[1]: https://github.com/ebullient/ttrpg-convert-cli/releases/latest [3]: docs/configuration.md +[4]: README.md ## Uh oh, something went wrong +### What are the weird characters in the output? +On Windows, the command output will look like this, with weird characters at the start of lines. +``` +[ Γ£à OK] Finished reading config. +ΓÅ▒∩╕Å Reading C:\Users\Kelly\Downloads\ttrpg-convert-cli-2.3.16-windows-x86_64\ttrpg-convert-cli-2.3.16-windows-x86_64\bin\5etools-mirror-2.github.io\data +[ Γ£à OK] Finished reading data. +``` +These are emoji that Windows is having trouble displaying. This doesn't affect the functionality at all, but +if you want to see these properly, choose a font with emoji support in the command line, and run the following: +``` +chcp 65001 +``` + +You should then start seeing the emoji correctly: +``` +[ ✅ OK] Finished reading config. +⏱️ Reading C:\Users\Kelly\Downloads\ttrpg-convert-cli-2.3.16-windows-x86_64\ttrpg-convert-cli-2.3.16-windows-x86_64\bin\5etools-mirror-2.github.io\data +[ ✅ OK] Finished reading data. +``` + +### 'ttrpg-convert' is not recognized +If you see the following: +``` +'ttrpg-convert' is not recognized as an internal or external command, +operable program or batch file. +``` +or +``` +ttrpg-convert : The term 'ttrpg-convert' is not recognized as the name of a cmdlet, function, script file, or operable +program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again. +At line:1 char:1 ++ ttrpg-convert ++ ~~~~~~~~~~~~~ + + CategoryInfo : ObjectNotFound: (ttrpg-convert:String) [], CommandNotFoundException + + FullyQualifiedErrorId : CommandNotFoundException +``` + +This means that the command line can't find the program. This is usually because you're running the command in +the wrong directory, or there's a typo somewhere in the name of the command. + +Type in `dir` and press **Enter**. You should see output similar to this: +``` + Directory: + C:\Users\Kelly\Downloads\ttrpg-convert-cli-2.3.16-windows-x86_64\ttrpg-convert-cli-2.3.16-windows-x86_64\bin + + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +d----- 29/06/2024 6:51 PM 5etools-mirror-2.github.io +-a---- 29/06/2024 4:17 PM 58880000 ttrpg-convert.exe +``` + +If there is no `ttrpg-convert.exe` in the list, then you're either in the wrong directory or have unzipped the +file to the wrong directory. Make sure that you're opening the command line in the directory that contains +`ttrpg-convert.exe`. + +If there *is* a `ttrpg-convert.exe` in the list, then the next most likely culprit is a typo. Make sure that the +command starts with `./ttrpg-convert`. Try copy/pasting this command: +``` +./ttrpg-convert --help +``` +If everything is set up correctly, you should see output starting with the following: +``` +Convert TTRPG JSON data to markdown +Usage: ttrpg-convert [-dhlvV] [--index] [-c=] [-g=] + -o= [] [...] [COMMAND] +``` + +### No output at all +If you don't get any output at all when running the `ttrpg-convert` command, try running +`./ttrpg-convert --help`. If you still get no output, like this: + +``` +C:\Users\Kelly\Downloads\ttrpg-convert-cli-2.3.14-windows-x86_64\bin>.\ttrpg-convert --help + +C:\Users\Kelly\Downloads\ttrpg-convert-cli-2.3.14-windows-x86_64\bin> +``` + +Then you probably have an anti-virus software that is blocking command line EXE files. The standard Windows +Defender doesn't do this, so it's probably some third-party anti-virus software you have installed. Try +disabling it temporarily, or allow-listing the `ttrpg-convert.exe` file. + +Note that this is often different from the Firewall settings and is often listed as a different feature with +with a different name, depending on what anti-virus software you're using. Sometimes this is called +*Realtime Protection*, or *Deep Behavioral Inspection*. + +### The current machine does not support all of the following CPU features that are required by the image + If you see the following: -> "The current machine does not support all of the following CPU features that are required by the image: +> The current machine does not support all of the following CPU features that are required by the image: > \[CX8, CMOV, FXSR, MMX, SSE, SSE2, SSE3, SSSE3, SSE4_1, SSE4_2, POPCNT, LZCNT, AVX, AVX2, BMI1, BMI2, FMA]. -> Please rebuild the executable with an appropriate setting of the -march option." +> Please rebuild the executable with an appropriate setting of the -march option. You have an older version of Windows. You'll need to use the [Java version](docs/alternateRun.md#use-java-to-run-the-jar) of the CLI instead. + +[Git]: https://git-scm.com/download/win diff --git a/README.md b/README.md index 0d67fbcb2..c0414a2f7 100644 --- a/README.md +++ b/README.md @@ -37,15 +37,11 @@ If you don't have a favorite method already, or you don't know what those words - Start with the built-in `Terminal` application. - [Learn the Mac OS X Command Line][] - For Windows Users: - - Use the native [Command Prompt][] - - [Open a command prompt in a folder (Windows)][] - - [Running executables from the command line (Windows)][] - - To show emoji in Windows Commmand Prompt: `chcp 65001` and choose a font with emoji support (Consolas is one). + - [A Beginner's Guide to the Windows Command Line][] + - See the [Windows README](README-WINDOWS.md) [Learn the Mac OS X Command Line]: https://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line -[Command Prompt]: https://www.digitaltrends.com/computing/how-to-use-command-prompt/ -[Open a command prompt in a folder (Windows)]: https://www.lifewire.com/open-command-prompt-in-a-folder-5185505 -[Running executables from the command line (Windows)]: https://www.techwalla.com/articles/how-to-use-quotcdquot-command-in-command-prompt-window +[A Beginner's Guide to the Windows Command Line]: https://www.makeuseof.com/tag/a-beginners-guide-to-the-windows-command-line/ ## Install the TTRPG Convert CLI diff --git a/docs/screenshots/windows-explorer-folder-context-menu.png b/docs/screenshots/windows-explorer-folder-context-menu.png new file mode 100644 index 000000000..506f70f7f Binary files /dev/null and b/docs/screenshots/windows-explorer-folder-context-menu.png differ diff --git a/docs/screenshots/windows-explorer-powershell-after-run.png b/docs/screenshots/windows-explorer-powershell-after-run.png new file mode 100644 index 000000000..20d77f40f Binary files /dev/null and b/docs/screenshots/windows-explorer-powershell-after-run.png differ diff --git a/docs/screenshots/windows-explorer-powershell-with-sources.png b/docs/screenshots/windows-explorer-powershell-with-sources.png new file mode 100644 index 000000000..5d9b357ed Binary files /dev/null and b/docs/screenshots/windows-explorer-powershell-with-sources.png differ diff --git a/docs/screenshots/windows-powershell-open.png b/docs/screenshots/windows-powershell-open.png new file mode 100644 index 000000000..b04f58360 Binary files /dev/null and b/docs/screenshots/windows-powershell-open.png differ