From f80fba4d24fddbac4f481c6639f7b334dec149a1 Mon Sep 17 00:00:00 2001
From: Terence <terence@trnc.co>
Date: Wed, 14 Oct 2020 19:18:11 +1300
Subject: [PATCH] Integrate README.md with new assets.md (#1293)

---
 README.md                         | 16 +++++++++++-----
 assets/README.md => doc/assets.md | 18 +++++++++++++-----
 2 files changed, 24 insertions(+), 10 deletions(-)
 rename assets/README.md => doc/assets.md (77%)

diff --git a/README.md b/README.md
index d4703245..522a4535 100644
--- a/README.md
+++ b/README.md
@@ -391,12 +391,14 @@ variable to make these changes permanent or use `bat`s
 
 ### Adding new syntaxes / language definitions
 
-`bat` uses the excellent [`syntect`](https://github.com/trishume/syntect/)
+Should you find a particular syntax is not available within `bat`, you can follow these instructions to easily add new syntaxes to your current `bat` installation. 
+
+By default, `bat` uses the excellent [`syntect`](https://github.com/trishume/syntect/)
 library for syntax highlighting. `syntect` can read any
 [Sublime Text `.sublime-syntax` file](https://www.sublimetext.com/docs/3/syntax.html)
-and theme. To add new syntax definitions, do the following.
+and theme. 
 
-Create a folder with syntax definition files:
+1. Create a folder with syntax definition files:
 
 ```bash
 mkdir -p "$(bat --config-dir)/syntaxes"
@@ -407,13 +409,13 @@ cd "$(bat --config-dir)/syntaxes"
 git clone https://github.com/tellnobody1/sublime-purescript-syntax
 ```
 
-Now use the following command to parse these files into a binary cache:
+2. Now use the following command to parse these files into a binary cache:
 
 ```bash
 bat cache --build
 ```
 
-Finally, use `bat --list-languages` to check if the new languages are available.
+3. Finally, use `bat --list-languages` to check if the new languages are available.
 
 If you ever want to go back to the default settings, call:
 
@@ -421,6 +423,10 @@ If you ever want to go back to the default settings, call:
 bat cache --clear
 ```
 
+4. If you think that a specific syntax should be included in `bat` by default, please 
+  consider opening a "syntax request" ticket after reading the policies and 
+  instructions [here](doc/assets.md)
+
 ### Adding new themes
 
 This works very similar to how we add new syntax definitions.
diff --git a/assets/README.md b/doc/assets.md
similarity index 77%
rename from assets/README.md
rename to doc/assets.md
index db87179f..20da7f55 100644
--- a/assets/README.md
+++ b/doc/assets.md
@@ -1,10 +1,12 @@
-## Syntax Highlighting in bat
+## Add New Syntax Highlighting into the bat binary
 
-`bat` uses the [syntect](https://github.com/trishume/syntect) library to highlight source
+Should you find a particular syntax is not available within `bat` and think it should be included in `bat` by default, you can follow the instructions and policies outlined below. 
+ 
+`bat` uses the excellent [syntect](https://github.com/trishume/syntect) library to highlight source
 code. As a basis, syntect uses [Sublime Text](https://www.sublimetext.com/) syntax definitions
 in the `.sublime-syntax` format.
 
-In order to add new syntaxes to `bat`, follow these steps:
+**Important:** Before proceeding, verify that the syntax you wish to add meets the [criteria for inclusion](#Criteria-for-inclusion-of-new-syntaxes).
 
 1. Find a Sublime Text syntax for the given language, preferably in a separate Git repository
    which can be included as a submodule (under `assets/syntaxes`).
@@ -13,13 +15,15 @@ In order to add new syntaxes to `bat`, follow these steps:
    Sublime Text and convert it to a `.sublime-syntax` file via *Tools* -> *Developer* ->
    *New Syntax from XXX.tmLanguage...*. Save the new file in the `assets/syntaxes` folder.
 
-3. Run the `create.sh` script. It calls `bat cache --build` to parse all available
+3. Run the `assets/create.sh` script. It calls `bat cache --build` to parse all available
    `.sublime-syntax` files and serialize them to a `syntaxes.bin` file (in this folder).
 
 4. Re-compile `bat`. At compilation time, the `syntaxes.bin` file will be stored inside the
    `bat` binary.
 
-5. If you send a pull request with your changes, please do *not* include the changed `syntaxes.bin`
+5. Use `bat --list-languages` to check if the new languages are available.
+
+6. If you send a pull request with your changes, please do *not* include the changed `syntaxes.bin`
    file. A new binary cache file will be created once before every new release of `bat`.
 
 ### Troubleshooting
@@ -50,3 +54,7 @@ The following files have been manually modified after converting from a `.tmLang
    https://github.com/seanjames777/SML-Language-Definition/blob/master/sml.tmLanguage
 * `Cabal.sublime_syntax` has been added manually from
   https://github.com/SublimeHaskell/SublimeHaskell/ - we don't want to include the whole submodule because it includes other syntaxes ("Haskell improved") as well.
+
+## Criteria for inclusion of new syntaxes
+
+* More than 10,000 downloads on packagecontrol.io/
\ No newline at end of file