Added documentation for the scope test format

Author: AndreasArvidsson

packages/cursorless-org-docs/src/docs/contributing/adding-a-new-scope.md

@@ -61,6 +61,7 @@ Then add parse tree patterns for the given scope to your language's `.scm` file
 - Use the [scope visualizer](../user/scope-visualizer.md) to see your scope highlighted in real time every time you save the `.scm` file.
 - Use the command `"parse tree <target>"` to see the parse tree for a given target. For example `"parse tree line"` will show you the parse tree for the current line, as well as all of its ancestors. This will generate a markdown file with parse tree info, which you can then use to write your patterns. You might find it helpful to open a markdown preview of the file.
 - You will likely want to look at `node-types.json` for your language, (eg [java](https://github.com/tree-sitter/tree-sitter-java/blob/master/src/node-types.json)). This file is generated from the language's `grammar.js`, which might also be helpful to look at (eg [java](https://github.com/tree-sitter/tree-sitter-java/blob/master/grammar.js)).
+- Documentation for the [scope test format](./scope-test-format.md)
 
 ## 6. Update the tests
 

packages/cursorless-org-docs/src/docs/contributing/parse-tree-patterns.md

@@ -1,4 +1,4 @@
-# Parse tree pattern matcher
+# Parse tree pattern matcher [DEPRECATED]
 
 We have a small domain-specific language that we use to define patterns to look for in tree-sitter parse trees. This DSL enables us to rapidly define new syntactic scope types and support new programming languages.
 

packages/cursorless-org-docs/src/docs/contributing/scope-test-format.md

@@ -0,0 +1,65 @@
+# Scope test format
+
+## Example
+
+Example of `.scope` file for the javascript if statement scope.
+
+```
+if (true) {
+
+}
+---
+
+[Content] =
+[Removal] =
+[Domain] = 0:0-2:1
+  >-----------
+0| if (true) {
+1|
+2| }
+   -<
+
+[Insertion delimiter] = "\n"
+```
+
+## Understanding the format
+
+General layout of a `.scope` file is:
+
+```
+Source code
+---
+Scopes
+```
+
+## Source code
+
+The code that you want to generate scopes for. We try to keep this as short and simple as possible while still containing the syntax you want to test.
+
+## Scopes
+
+One or more scopes found in the source code. Each scope is a collection of ranges as well as an insertion delimiter.
+
+A description of the different ranges and how they are used is available in our [glossary](https://www.cursorless.org/docs/user/glossary).
+
+### Scope ranges
+
+The below example indicates that the content range, removal range, and domain range was the same. Line 0, column 0, to line 2, column 1. These ranges could also be different and in that case each show up as a separate range.
+
+```
+[Content] =
+[Removal] =
+[Domain] = 0:0-2:1
+```
+
+Each range is also visualized:
+
+```
+  >-----------
+0| if (true) {
+1|
+2| }
+   -<
+```
+
+On the left hand side we first have the line numbers, a pipe separator, and finally the source code. The range is visualized by starting after `>` and ending before `<`. Note that `>` and `<` is excluded from the range. That means a range of length one is `>-<` and an empty range is `><`.