docs: update README

MinecraftCommands · Jun 28, 2024 · b831afb · b831afb
1 parent 478eae2
commit b831afb
Show file tree

Hide file tree

Showing 3 changed files with 240 additions and 59 deletions.
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -6,7 +6,6 @@ on:
     paths:
       - "mcfunction.*"
   push:
-    branches: [main]
     tags: ["v*.*.*"]
 
 jobs:
@@ -15,7 +14,7 @@ jobs:
 
     steps:
       # ---------------------------------------------
-      # -----           gather repo             -----
+      #  ----           gather repo             -----
       # ---------------------------------------------
       - uses: actions/checkout@v3
         with:
@@ -29,7 +28,7 @@ jobs:
         run: git checkout main
 
       # ---------------------------------------------
-      # -----           setup deps             -----
+      #  ----           setup deps             -----
       # ---------------------------------------------
       - name: Use Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v3
@@ -42,6 +41,7 @@ jobs:
           npm install -g @vscode/vsce
           npm install -g js-yaml
           npm install -g ovsx
+          npm install -g plist2
 
       - name: "Setup jq"
         uses: dcarbone/install-jq-action@v2
@@ -50,10 +50,12 @@ jobs:
           force: true
 
       # ---------------------------------------------
-      # -----         generate files           -----
+      #  ----         generate files           -----
       # ---------------------------------------------
-      - name: Export JSON from YAML
-        run: js-yaml mcfunction.tmLanguage.yaml > mcfunction.tmLanguage.json
+      - name: Export YAML -> JSON -> PLIST
+        run: |
+          js-yaml mcfunction.tmLanguage.yaml > mcfunction.tmLanguage.json
+          plist2 mcfunction.tmLanguage.json mcfunction.tmLanguage
 
       - id: version
         name: Version
@@ -63,15 +65,15 @@ jobs:
           echo "ext=syntax-mcfunction-$VERSION.vsix" >> "$GITHUB_OUTPUT"
 
       # ---------------------------------------------
-      # -----           push files             -----
+      #  ----           push files             -----
       # ---------------------------------------------
       - name: Push JSON to repo for sublime (if not matched)
         if: github.ref == 'refs/heads/main'
         run: |
           git config --global user.name "github-actions"
           git config --global user.email "[email protected]"
-          git add mcfunction.tmLanguage.json
-          git commit -m "🤖 Generate JSON"
+          git add mcfunction.tmLanguage.json mcfunction.tmLanguage
+          git commit -m "🤖 Generate JSON/PLIST"
           git push origin main
         continue-on-error: true
 
@@ -83,11 +85,11 @@ jobs:
           git config --global user.name "github-actions"
           git config --global user.email "[email protected]"
           git add package.json
-          git commit -m "🤖 Bump version"
+          git commit -m "🎉 Release ${{ steps.version.outputs.v }}"
           git push origin main
 
       # ---------------------------------------------
-      # -----             release              -----
+      #  ----             release              -----
       # ---------------------------------------------
       - id: package
         name: Package VSCode Ext
@@ -112,6 +114,10 @@ jobs:
             mcfunction.tmLanguage.yaml
             mcfunction.tmLanguage.json
 
+      - name: Release to vsce
+        if: startsWith(github.ref, 'refs/tags/')
+        run: vsce publish
+
       - name: Release to openvsix
         if: startsWith(github.ref, 'refs/tags/')
         run: npx ovsx publish ${{ steps.version.outputs.ext }} -p ${{ secrets.OVSX }}
diff --git a/README.md b/README.md
@@ -10,26 +10,21 @@ Give this repo a ⭐ if you like it!
 
 ![demo](https://raw.githubusercontent.com/MinecraftCommands/syntax-mcfunction/main/imgs/preview.png)
 
-## Goals
+This project contains syntax definitions for Minecraft commands (`.mcfunction`) using the textmate grammer spec. It is a general, feature complete language spec built via generic syntatical components that describe the language (aka, mimimal hardcoded command support). This means it should support future game versions, many modded commands, and even custom language compilers such as [bolt](https://github.com/mcbeet/bolt) and [jmc](https://jmc.wingedseal.com/).
 
-The aim of this syntax definition is to provide a general, feature complete language spec for Minecraft commands. It is **not** geared towards error checking or the specific commands and specifically contains **zero** error highlighting, allowing for decent highlighting of invalid or custom pre-processed command scripts.
-
-## TODOs
-
-- [x] Add explicit macro support
-- [x] Fix issues with nbt and other suffixes on numbrs
-- [x] Fix issues on resource names versus keywords
-- [ ] Add tests for Bedrock
-- [ ] (VSCode & Sublime) Add jsonschema file for `pack.mcmeta`
-- [-] Compare w/ `language-mcfunction` to synchronize scope names
-  - Likely won't get better than this tbh, will need feedback
+> [!Warning]
+> This syntax does **not** contain any error highlighting meaning invalid commands will highlight correctly. If you are looking error validation and auto-complete for vanilla commands, we recommend the [Spyglass](https://spyglassmc.com/) project for a language-server that builds upon this simple grammar!
 
 ## Installing
 
 ### [VSCode Extension](https://marketplace.visualstudio.com/items?itemName=MinecraftCommands.syntax-mcfunction)
 
 Install the extension from the [marketplace](https://marketplace.visualstudio.com/items?itemName=MinecraftCommands.syntax-mcfunction) or by searching for `syntax-mcfunction` in the extensions tab.
 
+### [open-vsix Extension](https://open-vsx.org/extension/MinecraftCommands/syntax-mcfunction)
+
+Follow these [instructions](https://github.com/eclipse/openvsx/wiki/Using-Open-VSX-in-VS-Code) if you are looking on using the open-vsix version of this project in VSCode or any of it's forks.
+
 ### Sublime Text
 
 It is recommended you use [Package Control](https://packagecontrol.io/) to manage the package:
@@ -49,6 +44,22 @@ This will keep the package updated with the repository automatically.
 
 Otherwise you can clone the repository into user packages (e.g. `%appdata%\Sublime Text 3\Packages`) and update it manually.
 
+## `language-mcfunction`
+
+While this grammar was created from scratch, much of it's work was adapted from the original [`language-mcfunction`](https://github.com/arcensoth/language-mcfunction) grammar. One of the original ideas for `language-mcfunction` was to develop a general, simpler version for `mcfunction`.
+
+> [!Note]
+> Actually, an earlier prototype of this grammar was going to be used as a base for a `language-mcfunction` rewrite.
+
+There are some key differences to note between this syntax and the original:
+- `language-mcfunction` is designed to operate on singular lines. If one line is broken, it does not affect lines after it and commands **cannot** span across multiple lines at all.
+  - This was the core issue that caused me to develop `syntax-mcfunction` (even before Minecraft 1.20.2 introduced multi-line commands) as I needed a grammar that had multi-line support.
+- `language-mcfunction` contains specific commands validation and reports errors for invalid commands
+  - `syntax-mcfunction` differs in philosophy here. Textmate grammars are not well-equipped to actually validate commands — that's more of a role for language servers.
+  - This project also generally highlights commands as it allows for easier maintenance and is better for platforms such as Github where multiple command extensions / modded commands might reuse the `.mcfunction` extension.
+
+Due to these, coloring and highlighting will vary in a couple of places when comparing these grammars. While the goal is to match `language-mcfunction` as close as possible, there will never be a true 1:1 match in highlighting as the entire design of the grammar differs.
+
 ## Contributing
 
 We are happy to accept any PRs just make sure to make a cooresponding issue first to track it. When making a PR, make sure the branch of your fork is **not** `main` and also make sure maintainers are allowed to edit your PR. This is helpful for me making small edits to the PR before merging.
@@ -59,6 +70,19 @@ We only require edits to the `yaml` file as the `json` and `plist` files are gen
 npx js-yaml mcfunction.tmLanguage.yaml > mcfunction.tmLanguage.json
 ```
 
+### Making Releases
+
+Releases are semi-automated in this repo. Once your PR is merged into the `main` branch, the maintainer will create a new tag to trigger our Github CI to produce a new version.
+
+```bash
+git tag -a v1.2.3
+git push --tags
+```
+
+This will generate the json and plist variations of the grammar, create and push a `.vsix` extension to the VSCode and open-vsix marketplaces, and create a release in the [releases](https://github.com/MinecraftCommands/syntax-mcfunction/releases) tab.
+
+The maintainer will then need to manually fill in the body of the release to add in the changelog and links.
+
 ## Acknowledgements
 
 This repo is entirely dedicated to our beloved community member and friend, [Arcensoth](https://github.com/Arcensoth). His work on the original [language-mcfunction](https://github.com/Arcensoth/language-mcfunction) and overall contributions to the Minecraft Commands community was invaluable and he will be missed.