f80fba4 · bat · git.iko.soy

git.iko.soy/bat

Integrate README.md with new assets.md (#1293)

commitf80fba4d24fddbac4f481c6639f7b334dec149a1 authorTerence <terence@trnc.co> dateWed 14 Oct 2020, 19:18 (6 years ago) parentd075d2b

2 files changed+24−10

compare with master

unifiedsplit

README.md+11−5 assets/README.md → doc/assets.md+13−5

README.md+11−5

@@ -391,12 +391,14 @@ variable to make these changes permanent or use `bat`s

391391

392392### Adding new syntaxes / language definitions

393393

394−`bat` uses the excellent [`syntect`](https://github.com/trishume/syntect/)

394+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.

395+

396+By default, `bat` uses the excellent [`syntect`](https://github.com/trishume/syntect/)

395397library for syntax highlighting. `syntect` can read any

396398[Sublime Text `.sublime-syntax` file](https://www.sublimetext.com/docs/3/syntax.html)

397−and theme. To add new syntax definitions, do the following.

399+and theme.

398400

399−Create a folder with syntax definition files:

401+1. Create a folder with syntax definition files:

400402

401403```bash

402404mkdir -p "$(bat --config-dir)/syntaxes"

@@ -407,13 +409,13 @@ cd "$(bat --config-dir)/syntaxes"

407409git clone https://github.com/tellnobody1/sublime-purescript-syntax

408410```

409411

410−Now use the following command to parse these files into a binary cache:

412+2. Now use the following command to parse these files into a binary cache:

411413

412414```bash

413415bat cache --build

414416```

415417

416−Finally, use `bat --list-languages` to check if the new languages are available.

418+3. Finally, use `bat --list-languages` to check if the new languages are available.

417419

418420If you ever want to go back to the default settings, call:

419421

@@ -421,6 +423,10 @@ If you ever want to go back to the default settings, call:

421423bat cache --clear

422424```

423425

426+4. If you think that a specific syntax should be included in `bat` by default, please

427+ consider opening a "syntax request" ticket after reading the policies and

428+ instructions [here](doc/assets.md)

429+

424430### Adding new themes

425431

426432This works very similar to how we add new syntax definitions.

assets/README.md → doc/assets.mdrenamed+13−5

@@ -1,10 +1,12 @@

1−## Syntax Highlighting in bat

1+## Add New Syntax Highlighting into the bat binary

3−`bat` uses the [syntect](https://github.com/trishume/syntect) library to highlight source

3+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.

5+`bat` uses the excellent [syntect](https://github.com/trishume/syntect) library to highlight source

46code. As a basis, syntect uses [Sublime Text](https://www.sublimetext.com/) syntax definitions

57in the `.sublime-syntax` format.

7−In order to add new syntaxes to `bat`, follow these steps:

9+**Important:** Before proceeding, verify that the syntax you wish to add meets the [criteria for inclusion](#Criteria-for-inclusion-of-new-syntaxes).

810

9111. Find a Sublime Text syntax for the given language, preferably in a separate Git repository

1012 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:

1315 Sublime Text and convert it to a `.sublime-syntax` file via *Tools* -> *Developer* ->

1416 *New Syntax from XXX.tmLanguage...*. Save the new file in the `assets/syntaxes` folder.

1517

16−3. Run the `create.sh` script. It calls `bat cache --build` to parse all available

18+3. Run the `assets/create.sh` script. It calls `bat cache --build` to parse all available

1719 `.sublime-syntax` files and serialize them to a `syntaxes.bin` file (in this folder).

1820

19214. Re-compile `bat`. At compilation time, the `syntaxes.bin` file will be stored inside the

2022 `bat` binary.

2123

22−5. If you send a pull request with your changes, please do *not* include the changed `syntaxes.bin`

24+5. Use `bat --list-languages` to check if the new languages are available.

25+

26+6. If you send a pull request with your changes, please do *not* include the changed `syntaxes.bin`

2327 file. A new binary cache file will be created once before every new release of `bat`.

2428

2529### Troubleshooting

@@ -50,3 +54,7 @@ The following files have been manually modified after converting from a `.tmLang

5054 https://github.com/seanjames777/SML-Language-Definition/blob/master/sml.tmLanguage

5155* `Cabal.sublime_syntax` has been added manually from

5256 https://github.com/SublimeHaskell/SublimeHaskell/ - we don't want to include the whole submodule because it includes other syntaxes ("Haskell improved") as well.

57+

58+## Criteria for inclusion of new syntaxes

59+

60+* More than 10,000 downloads on packagecontrol.io/