Init a guide about R snippets

_quarto.yml

@@ -47,7 +47,7 @@ website:
       - text: "Help"
         href: troubleshooting.qmd
       - text: "<span class='btn btn-primary'>Download</span>"
-        href: download.qmd  
+        href: download.qmd
     right:
       - icon: github
         aria-label: 'Link to Positron Github Repository'
@@ -79,6 +79,7 @@ website:
         - section: "Migrating from RStudio"
           contents:
           - rstudio-rproj-file.qmd
+          - r-snippets.qmd
 
     - title: "Help"
       style: "docked"

r-snippets.qmd

@@ -0,0 +1,81 @@
+---
+title: "Snippets for R"
+---
+
+Code snippets let you insert ready-made templates for common coding patterns.
+For example, `for` is a reserved word in R that is used to create a loop.
+In actual usage, `for` is always part of a larger construct:
+
+```r
+for (variable in vector) {
+    # code to repeat
+}
+```
+
+A snippet for `for` inserts this whole skeleton, with special placeholders that let you use <kbd>Tab</kbd> to move through the positions for `variable` and `vector`, and `# code to repeat`.
+
+![Completion list after typing "for", showing the snippet that can be inserted](images/snippets-for-example){width=700}
+
+It is common for IDEs to provide explicit support for code snippets and this certainly holds true for RStudio and Positron.
+This guide is intended to help users who have used snippets in RStudio adapt their approach for Positron, which inherits snippet behaviour from its VS Code roots.
+
+Documentation on snippets in:
+
+* [RStudio](https://docs.posit.co/ide/user/ide/guide/productivity/snippets.html)
+* [VS Code](https://code.visualstudio.com/docs/editing/userdefinedsnippets)
+
+## Default and custom snippets in RStudio
+
+RStudio ships with a default set of snippets.
+For our purposes, it's useful to break them into two broad classes:
+
+* Reserved words: These snippets relate to keywords that have special meaning. This includes control flow elements, such as `if`, `while`, and `for`, as well as the `function` keyword.
+* Everything else: These snippets relate to a selection of functions, mostly in the so-called base packages. Examples include `matrix()`, the `apply()` family of functions, and various functions around S4 classes, such as `setClass()`.
+
+You can customize your RStudio snippets via the *Edit Snippets* button in *Global Options > Code*.
+Under the hood, this initializes a user-level snippet file that is pre-populated with RStudio's default snippets.
+You can then apply your desired changes, such as adding or deleting snippets.
+Going forward, this user-level file powers all of your RStudio snippets, i.e. there is no combining of built-in and user-level snippets.
+
+## Default and custom snippets in Positron
+
+The completion experience in Positron arises from two components working together:
+
+* Positron: The IDE controls the overall completion experience, which is the heart of the so-called [IntelliSense features](https://code.visualstudio.com/docs/editing/intellisense#_intellisense-features) in VS Code. IntelliSense provides the user interface for completions and is also in charge of combining/filtering/sorting completions coming from multiple sources, including snippets. These snippets can come from various sources:
+  - Extensions
+  - User settings
+  - Workspace settings
+* R language server: The [ark kernel](https://github.com/posit-dev/ark) provides an LSP server for R and, in particular, ark produces all (or almost all) of the completions you see for R.
+
+This division of labor means that the completion and snippet responsibilities are a bit different in Positron than in RStudio.
+
+### Reserved words
+
+In Positron, the completion items related to R's reserved words are built into ark.
+Each reserved word can be completed on its own and, in some cases, as part of a larger snippet.
+
+![Completion list with rectangles highlighting two entries for the `function` reserved word, one as a bare keyword completion and another as a snippet](images/snippets-keyword-with-two-items.png){width=700}
+
+### Everything else
+
+If you want snippets beyond those provided for R's reserved words, you'll need to configure that for yourself.
+Press <kbd>Cmd/Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> to open the command palette and type *Snippets: Configure Snippets*.
+
+Snippets can be stored in three types of files:
+
+1. "Global": contains snippets that are not limited to one language. Create with *New Global Snippets file...*.
+    - Individual snippets can have a `scope` which specifies one or more languages. Include `"r"` in the `scope` for any snippet you want to use in R.
+    - This writes a `.code-snippets` file alongside your other Positron user settings. It is pre-populated with example snippets for both R and Python.
+1. "Global" but for one workspace: contains snippets for multiple languages but tied to a specific workspace. Create with *New Snippets file for 'MyProject'*.
+    - This writes a `.code-snippets` file alongside the other settings for the workspace, pre-populated with example snippets.
+
+    ![Menu with options for "New Global Snippets file" and "New Snippets file for 'MyProject'"](images/snippets-configure-snippets.png){width=700}
+1. Language-specific: contains snippets for one specific language. Create by selecting the language from the drop-down menu, which includes entries for R, Python, and Quarto.
+
+    In the case of R, this writes an `r.json` file alongside your other Positron user settings. It is pre-populated with an R example snippet.
+
+    ![Menu with options for creating a new snippet file for Python, Quarto, or R](images/snippets-configure-language-specific-snippets.png){width=700}
+
+Although both RStudio and Positron keep track of custom snippets in a file, they don't use the same syntax.
+Positron uses the TextMate syntax, which is inherited from VS Code.
+If you miss specific snippets from RStudio's defaults, you can consult this file to see what they look like when translated to the syntax used by Positron: [`r.code-snippets`](https://github.com/posit-dev/ark/blob/19337a1b41e8c5a3a77ac61db93b7c6bf6cdc8a3/crates/ark/resources/snippets/r.code-snippets).