Replace X placeholder with environment variable (#1912)

The contributing docs that explain how to add and update a programming
language use a placeholder `X` to refer to the name of the language.
This commit updates the docs to use `$PL` as the placeholder instead.

Using `$PL` makes it easier to copy and run the code samples in the
documentation, and `$PL` is more descriptive than simply `$X`.

Author: savq

docs/contributing/adding-a-language.md

@@ -17,7 +17,7 @@ Otherwise, let's get started.
 Repositories involved directly:
 * [semgrep](https://github.com/semgrep/semgrep): the semgrep command line program;
 * [ocaml-tree-sitter-semgrep](https://github.com/semgrep/ocaml-tree-sitter-semgrep): language-specific setup, generates C/OCaml parsers for semgrep;
-* new repo semgrep-_X_ for the new language _X_: C/OCaml parser generated from ocaml-tree-sitter-semgrep by an admin.
+* A new repo `semgrep-$PL` for the language `$PL`: C/OCaml parser generated from ocaml-tree-sitter-semgrep by an admin.
 
 Submodules overview (semgrep repo)
 --
@@ -36,7 +36,8 @@ repository](https://github.com/semgrep/semgrep):
     └── semgrep-ruby
 ```
 
-When done with the work in [ocaml-tree-sitter-semgrep](https://github.com/semgrep/ocaml-tree-sitter-semgrep), you'll need a new repo semgrep-X to host the generated parser code.
+When done with the work in [ocaml-tree-sitter-semgrep](https://github.com/semgrep/ocaml-tree-sitter-semgrep),
+you'll need a new repo `semgrep-$PL` to host the generated parser code.
 Ask someone from the Semgrep team to create one for you. For this, they should use
 the template
 [semgrep-lang-template](https://github.com/semgrep/semgrep-lang-template)
@@ -70,16 +71,16 @@ what's going on or to set things up manually.
 
 From the ocaml-tree-sitter repo, do the following:
 
-1. Create a `lang/X` folder.
+1. Create a `lang/$PL` folder.
 2. Make a `test/ok` directory. Inside the directory,
    create a simple `hello-world` program for the language you are porting.
    Name the program `hello-world.<ext>`.
 3. Now make a file called `extensions.txt` and input all the language extensions
    (.rb, .kt, etc) for your language in the file.
 4. Create a file called `fyi.list` with all the information files, such as
-    `semgrep-grammars/src/tree-sitter-X/LICENSE`,
-    `semgrep-grammars/src/tree-sitter-X/grammar.js`,
-    `semgrep-grammars/src/semgrep-X/grammar.js`, etc.
+    `semgrep-grammars/src/tree-sitter-$PL/LICENSE`,
+    `semgrep-grammars/src/tree-sitter-$PL/grammar.js`,
+    `semgrep-grammars/src/semgrep-$PL/grammar.js`, etc.
    to bundle with the final OCaml/C project.
 5. Link the Makefile.common to a Makefile in the directory with:
    `ln -s ../Makefile.common Makefile`
@@ -88,7 +89,7 @@ From the ocaml-tree-sitter repo, do the following:
      on which to run parsing stats. Run with the following command:
      `./scripts/most-starred-for-language <lang> <github_username> <api_key>`
    * Using github advanced search to find the most starred or most forked repositories.
-7. Copy the generated `projects.txt` file into the `lang/X` directory.
+7. Copy the generated `projects.txt` file into the `lang/$PL` directory.
 8. Add in extra projects and extra input sets as you see necessary.
 
 Here's the file hierarchy for Ruby:
@@ -116,7 +117,7 @@ then run some tests for the parser. Full instructions for this
 are given in [updating-a-grammar](updating-a-grammar.md) under
 "Testing". The short instructions are:
 1. For the first time, build everything with `./scripts/rebuild-everything`.
-2. Subsequently, work from the `lang/X` folder and run
+2. Subsequently, work from the `lang/$PL` folder and run
    `make` and `make test`.
 
 ### The `fyi.list` file
@@ -154,12 +155,12 @@ the semgrep ellipsis `...` usually needs to be added as well.
 You'll need to learn [how to create tree-sitter
 grammars](https://tree-sitter.github.io/tree-sitter/creating-parsers).
 
-1. Work from `semgrep-grammars/src/semgrep-X` and use `make` and
+1. Work from `semgrep-grammars/src/semgrep-$PL` and use `make` and
    `make test` to build and test.
 2. Add new test cases to `test/corpus/semgrep.text`.
 3. Edit `grammar.js`.
 4. Refer to the original grammar in
-   `semgrep-grammars/src/tree-sitter-X` to determine which rules to
+   `semgrep-grammars/src/tree-sitter-$PL` to determine which rules to
    extend.
 
 For an example of how to extend a language, you can:
@@ -243,9 +244,9 @@ branch, do the following:
    applicable) look clean and have minimal external dependencies.
 2. In `ocaml-tree-sitter/lang/Makefile`, add language under
    'SUPPORTED_LANGUAGES' and 'STAT_LANGUAGES'.
-3. In `ocaml-tree-sitter/lang` directory, run `./release X --dry-run`.
+3. In `ocaml-tree-sitter/lang` directory, run `./release $PL --dry-run`.
    If this looks good, please [ask someone from the Semgrep team](https://github.com/semgrep/ocaml-tree-sitter-semgrep/blob/main/doc/release.md) to
-   publish the code using `./release X`.
+   publish the code using `./release $PL`.
 
 ### Troubleshooting
 
@@ -267,7 +268,7 @@ Here are some known types of parsing errors:
 
 * A syntax error. The input program is in the wrong syntax or uses a
   recent feature that's not supported yet: `make test` or directly the
-  `parse_X` program will show the tree produced by tree-sitter with
+  `parse_$PL` program will show the tree produced by tree-sitter with
   one or more `ERROR` nodes.
 * A "reparsing" error. It's an error generated after the first
   successful parsing pass by the tree-sitter parser, during the
@@ -298,13 +299,13 @@ languages in pfff.
 Look under **Adding a Language** in [pfff](https://github.com/semgrep/pfff/blob/develop/README.md)
 for step-by-step instructions.
 
-## semgrep-core
+### semgrep-core
 
-Now that you have added your new language 'X' to pfff, do the following:
+Now that you have added your new language `$PL` to pfff, do the following:
 1. Add the new pfff submodule to semgrep-core.
-2. In `Check_pattern.ml`, add 'X' to `lang_has_no_dollar_ids`/ If the grammar
+2. In `Check_pattern.ml`, add `$PL` to `lang_has_no_dollar_ids`/ If the grammar
    has no dollar identifiers, add it above 'true'. Otherwise, add it above 'false'.
-3. In `synthesizing/Pretty_print_generic.ml`, add 'X' to the appropriate functions:
+3. In `synthesizing/Pretty_print_generic.ml`, add `$PL` to the appropriate functions:
    * print_bool
    * if_stmt
    * while_stmt
@@ -331,11 +332,11 @@ Now that you have added your new language 'X' to pfff, do the following:
             Parallel.invoke Tree_sitter_X.Parse.file file ()
         )
    ```
-6. In `parsing/tree_sitter/dune`, add `tree-sitter-lang.X`.
-7. Write a basic test case for your language in `tests/X/hello-world.X`. This can
+6. In `parsing/tree_sitter/dune`, add `tree-sitter-lang.$PL`
+7. Write a basic test case for your language in `tests/$PL/hello-world.$PL`. This can
    just be a hello-world function.
 8. Test that the command
-   `semgrep-core/bin/semgrep-core -dump_tree_sitter_cst test/X/hello-world`
+   `semgrep-core/bin/semgrep-core -dump_tree_sitter_cst test/$PL/hello-world`
    prints out a CST for your language.
 
 ## Legal concerns

docs/contributing/updating-a-grammar.md

@@ -4,22 +4,23 @@ slug: updating-a-grammar
 How to upgrade the grammar for a language
 ==
 
-Like for adding a language, most of these instructions happen in `ocaml-tree-sitter`.  
+Like for adding a language, most of these instructions happen in
+[ocaml-tree-sitter-semgrep](https://github.com/semgrep/ocaml-tree-sitter-semgrep).
 
-Let's call our language "X".
+Let's assume we are upgrading the grammar for the programming language `$PL`.
+(Consider adding an environment variable to your shell to make copying some of the commands below easier).
 
 Summary (ocaml-tree-sitter)
 --
 
 In ocaml-tree-sitter:
-1. Update submodule tree-sitter-X.
-2. From `lang/`, run `./test-lang X`.
-3. From `lang/`, ask a Semgrep team developer to run `./release X`.
+1. Update submodule `tree-sitter-$PL`.
+2. From `lang/`, run `./test-lang $PL`.
+3. From `lang/`, ask a Semgrep team developer to run `./release $PL`.
 
 In semgrep:
-1. In the semgrep repo, update submodule semgrep-X.
-2. In the semgrep repo, update the OCaml code that maps the CST to the
-   generic AST.
+1. In the semgrep repo, update submodule `semgrep-$PL`.
+2. In the semgrep repo, update the OCaml code that maps the CST to the generic AST.
 
 In the end, **make sure the generated code used by the main branch of
 semgrep can be regenerated** from the main branch of ocaml-tree-sitter:
@@ -36,29 +37,29 @@ Here are the main components:
   [ocaml-tree-sitter](https://github.com/semgrep/ocaml-tree-sitter-semgrep):
   generates OCaml parsing code from tree-sitter grammars extended
   with `...` and such. Publishes code into the git repos of the
-  form `semgrep-X`.
-* the original tree-sitter grammar `tree-sitter-X` e.g.,
+  form `semgrep-$PL`.
+* the original tree-sitter grammar `tree-sitter-$PL` e.g.,
   [tree-sitter-ruby](https://github.com/tree-sitter/tree-sitter-ruby):
   the original tree-sitter grammar for the language.
-  This is the git submodule `lang/semgrep-grammars/src/tree-sitter-X`
+  This is the git submodule `lang/semgrep-grammars/src/tree-sitter-$PL`
   in ocaml-tree-sitter. It is installed at the project's root
   in `node_modules` by invoking `npm install`.
 * syntax extensions to support semgrep patterns, such as ellipses
   (`...`) and metavariables (`$FOO`).
-  This is `lang/semgrep-grammars/src/semgrep-X`. It can be tested from
+  This is `lang/semgrep-grammars/src/semgrep-$PL`. It can be tested from
   that folder with `make && make test`.
-* an automatically-modified grammar for language X in `lang/X`.
+* an automatically-modified grammar for language `$PL` in `lang/$PL`.
   It is modified so as to accommodate various requirements of the
-  ocaml-tree-sitter code generator. `lang/X/src` and
-  `lang/X/ocaml-src` contain the C/C++/OCaml code that will published
-  into semgrep-X e.g.
+  ocaml-tree-sitter code generator. `lang/$PL/src` and
+  `lang/$PL/ocaml-src` contain the C/C++/OCaml code that will published
+  into `semgrep-$PL` e.g.
   [semgrep-ruby](https://github.com/semgrep/semgrep-ruby)
   and used by semgrep.
-* [semgrep-X](https://github.com/semgrep/semgrep-ruby):
+* [semgrep-$PL](https://github.com/semgrep/semgrep-ruby):
   provides generated OCaml/C parsers as a dune project. Is a submodule
   of semgrep.
 * [semgrep](https://github.com/semgrep/semgrep): uses the parsers
-  provided by semgrep-X, which produce a CST. The
+  provided by `semgrep-$PL`, which produce a CST. The
   program's CST or pattern's CST is further transformed into an AST
   suitable for pattern matching.
 
@@ -71,27 +72,27 @@ Before upgrading
 
 Make sure the `grammar.js` file or equivalent source files
 defining the grammar are included in the `fyi.list` file in
-`ocaml-tree-sitter/lang/X`.
+`ocaml-tree-sitter/lang/$PL`.
 
 Why: It is important for tracking and _understanding_ the changes made at the
 source.
 
 How: See [How to add support for a new language](adding-a-language.md).
 
-Upgrade the tree-sitter-X submodule
+Upgrade the tree-sitter-$PL submodule
 --
 
-Say you want to upgrade (or downgrade) tree-sitter-X from some old
+Say you want to upgrade (or downgrade) `tree-sitter-$PL` from some old
 commit to commit `602f12b`. This uses the git submodule way, without
 anything weird. The commands might be something like this:
 
 ```
 git submodule update --init --recursive --depth 1
-git checkout -b upgrade-X
-cd lang/semgrep-grammars/src/tree-sitter-X
-  git fetch origin --unshallow
-  git checkout 602f12b
-  cd ..
+git checkout -b upgrade-$PL
+cd lang/semgrep-grammars/src/tree-sitter-$PL
+git fetch origin --unshallow
+git checkout 602f12b
+cd ..
 ```
 
 Testing
@@ -112,7 +113,7 @@ commands will build and test the language:
 
 ```
 cd lang
-  ./test-lang X
+  ./test-lang $PL
 ```
 
 :::caution
@@ -122,7 +123,7 @@ correspond to [missing tokens](https://github.com/tree-sitter/tree-sitter/issues
 
 Check with:
 ```
-grep Blank lang/X/ocaml-src/lib/CST.ml
+grep Blank lang/$PL/ocaml-src/lib/CST.ml
 ```
 If anything comes up, you must modify the grammar so as to create
 a named rule for the node of the `Blank` kind. Eventually, the generated
@@ -131,19 +132,19 @@ Where a `Blank` node exists, we won't be able to get a token or its location
 at parsing time.
 
 If this works, we're all set. Commit the new commit for the
-tree-sitter-X submodule:
+`tree-sitter-$PL` submodule:
 ```
 git status
-git commit semgrep-languages/semgrep-X
-git push origin upgrade-X
+git commit semgrep-languages/semgrep-$PL
+git push origin upgrade-$PL
 ```
 
 Then make a pull request to merge this into ocaml-tree-sitter's
 main branch. It's ok to merge at this point, even if the generated code
 hasn't been exported (**Publishing** section below) or if you haven't
 done the necessary changes in semgrep (**Semgrep integration** below).
 
-We can now consider publishing the code to semgrep-X.
+We can now consider publishing the code to `semgrep-$PL`.
 
 Publishing
 --
@@ -153,18 +154,18 @@ _Please [ask someone at Semgrep, Inc. to run this step](https://github.com/semgr
 From the `lang` folder of ocaml-tree-sitter, we'll perform the
 release. This step redoes some of the work that was done earlier and
 checks that everything is clean before committing and pushing the
-changes to semgrep-X.
+changes to semgrep-$PL.
 
 ```
 cd lang
-  ./release --dry-run X  # dry-run release
-  ...                    # 'git status' will show changes for language X
-  ./release X  # commits and pushes to semgrep-X
+  ./release --dry-run $PL  # dry-run release
+  ...                    # 'git status' will show changes for language $PL
+  ./release $PL  # commits and pushes to semgrep-$PL
 ```
 
 This step is safe. Semgrep at this point is unaffected by those
 changes. There is now a new commit at
-`https://github.com/semgrep/semgrep-X` e.g.
+`https://github.com/semgrep/semgrep-$PL` e.g.
 https://github.com/semgrep/semgrep-javascript.
 The [`fyi/` folder](https://github.com/semgrep/semgrep-javascript/tree/main/fyi)
 contains original files from which the code was generated.
@@ -175,10 +176,10 @@ got the correct version of `grammar.js` or some other source file.
 Semgrep integration
 --
 
-From the semgrep repository, point the submodule for semgrep-X to the
+From the semgrep repository, point the submodule for `semgrep-$PL` to the
 latest commit from the "Publishing" step. Then rebuild semgrep-core,
 which will normally fail if the grammar changed. If the source
-`grammar.js` was included in the `fyi` folder for `semgrep-X` (as it
+`grammar.js` was included in the `fyi` folder for `semgrep-$PL` (as it
 should), `git diff HEAD^` should help figure out the changes since the
 last version.