Merge branch 'main' into enhance-service-documentation

Author: savetheclocktower

.github/workflows/build.yml

@@ -38,14 +38,11 @@ jobs:
     - name: Build Site
       run: npm run build
 
-    - name: Setup Pages
-      uses: actions/configure-pages@v3
-
     - name: Upload Artifact
-      uses: actions/upload-pages-artifact@v1
+      uses: actions/upload-pages-artifact@v3
       with:
         path: "./_dist"
 
     - name: Deploy to GitHub pages
       id: deployment
-      uses: actions/deploy-pages@v2
+      uses: actions/deploy-pages@v4

docs/contributing-to-pulsar/building-pulsar.md

@@ -61,13 +61,15 @@ zypper in libX11-devel libxkbfile-devel libsecret-devel
 
 @tab macOS
 
-```sh
-TODO
-```
+macOS installations must have the components described on the [Installing dependencies for some community packages](/getting-started/dependencies-for-some-community-packages/#macos) page.
+
+You can run `xcode-select --install` to setup these build tools if you think they’re not already present. You _do not_ need a full installation of Xcode.
 
 @tab Windows
 
-Firstly install [Visual Studio](https://visualstudio.microsoft.com/downloads/) from Microsoft.
+Install all of the components described on the [Installing dependencies for some community packages](/getting-started/dependencies-for-some-community-packages/#installing-visual-studio-tools) page.
+
+In particular, you must have either Visual Studio or Visual Studio Tools (_not_ Visual Studio Code) and the “Desktop development with C++” component must be enabled.
 
 :::
 
@@ -119,15 +121,15 @@ These instructions will also build `ppm` (Pulsar Package Manager) but it will re
 
 The following will allow you to build Pulsar as a stand alone binary or installer. After running you will find your built application in `pulsar/binaries`.
 
-The build script will automatically build for your system's CPU architecture, for example building on an `x86_64` CPU will produce binaries for `x86_64`, building on `arm64` will only produce binaries for `arm64`.
+The build script will automatically build for your system’s CPU architecture. For example, building on an `x86_64` CPU will produce binaries for `x86_64`, and building on `arm64` will only produce binaries for `arm64`.
 
-It is not possible to “cross-build” for different OSs. For Linux binaries you must build from a Linux machine; macOS binaries must be built from macOS; and so on. Your OS is detected automatically and the script will build the correct binaries for it.
+It is not possible to “cross-build” for different OSes. For Linux binaries you must build from a Linux machine; macOS binaries must be built from macOS; and so on. Your OS is detected automatically and the script will build the correct binaries for it.
 
 ::: tabs#core-hacking
 
 @tab Linux
 
-By default, running `yarn dist` will attempt to create `appimage` (for most Linux distributions), `deb` (for Debian or Ubuntu based distributions) and `rpm` (for Red Hat or Fedora based distributions) binaries but you can select the actual target you want to build by appending the above targets to the command. e.g.:
+By default, running `yarn dist` will attempt to create `AppImage` (for most Linux distributions), `deb` (for Debian or Ubuntu based distributions) and `rpm` (for Red Hat or Fedora based distributions) binaries but you can select the actual target you want to build by appending the above targets to the command. e.g.:
 
 - `yarn dist appimage`
 - `yarn dist deb`

docs/contributing-to-pulsar/contributing-to-official-pulsar-packages.md

@@ -15,33 +15,40 @@ The first step is creating your own clone. For some packages, you may also need
 
 For example, if you want to make changes to the {tree-view} package, fork the Pulsar repo on your GitHub account, then clone it:
 
-
 ```sh
 $ git clone https://github.com/[your-github-username]/pulsar.git
 ```
 
+:::tip
+
+Elsewhere in the docs, we explore the scenario where you want to run _all_ of Pulsar from source; **none of that is necessary** for this scenario. Our goal here is simply to get a single builtin package’s source code to live on your local disk so you can link to it in dev mode; the rest of the checked-out codebase can be ignored.
+
+:::
+
 From the root of where you cloned the repo on your disk, navigate to the `tree-view` package’s directory and install its dependencies:
 
 ```sh
-$ cd packages/tree-view
+$ cd <path-to-pulsar-repo>/packages/tree-view
 $ pulsar -p install
 > Installing modules ✓
 ```
 
-Now you can link it to development mode so when you run an Pulsar window with `pulsar -p --dev`, it’ll load your fork instead of the built in package:
+Now you can link it to development mode so that, when you run a Pulsar window with `pulsar -p --dev`, it’ll load your fork instead of the built in package:
 
 ```sh
 $ pulsar -p link --dev
 ```
 
 ### Running in development mode
 
-Editing a package in Pulsar is a bit of a circular experience: you're using Pulsar to modify itself. What happens if you temporarily break something? You don't want the version of Pulsar you're using to edit to become useless in the process. For this reason, it’s a good idea to load packages in **development mode** while you are working on them. You’ll perform your editing in **stable mode**, only switching to development mode to test your changes.
+Editing a package in Pulsar is a bit of a circular experience: you’re using Pulsar to modify itself. What happens if you temporarily break something? You don’t want the version of Pulsar you’re using to edit to become useless in the process.
+
+For this reason, it’s a good idea to load packages in **development mode** while you are working on them. You’ll perform your editing in **stable mode**, only switching to development mode to test your changes.
 
 To open a development mode window, use the **Application: Open Dev** command. You can also run dev mode from the command line with `pulsar --dev`.
 
 To load your package in development mode, create a symlink to it in <span class="platform-mac platform-linux">`~/.pulsar/dev/packages`</span><span class="platform-win">`%USERPROFILE%\.pulsar\dev\packages`</span>. This occurs automatically when you clone the package with `pulsar -p develop`. You can also run `pulsar -p link --dev` and `pulsar -p unlink --dev` from the package directory to create and remove dev-mode symlinks.
 
 ### Installing dependencies
 
-You'll want to keep dependencies up to date by running `pulsar -p update` after pulling any upstream changes.
+You’ll want to keep dependencies up to date by running `pulsar -p update` after pulling any upstream changes.

docs/contributing-to-pulsar/hacking-on-the-core.md

@@ -3,29 +3,92 @@ title: Hacking on the core
 layout: doc.ejs
 ---
 
-You will first want to build and run Pulsar [from source](../building-pulsar/).
+If you’re hitting a bug in Pulsar or just want to experiment with adding a feature to the core of the system, you’ll want to run Pulsar in dev mode with access to a local copy of the Pulsar source.
+
+## Check out the source code
+
+Check out the Pulsar source from GitHub into a directory of your choosing:
+
+```sh
+$ git clone [email protected]:pulsar-edit/pulsar.git
+```
+
+## Set up dependencies
+
+You should install a compatible version of Node. Read the `.nvmrc` file to learn which version of Node is best to use. If you don’t have one yet, you’ll probably find it useful to install a tool like <span class="platform-linux platform-mac"><a href="https://github.com/nvm-sh/nvm">NVM</a> or <a href="https://asdf-vm.com/">asdf</a></span><span class="platform-win"><a href="https://github.com/coreybutler/nvm-windows">NVM for Windows</a> or <a href="https://github.com/Schniz/fnm">fnm</a></span> to manage multiple versions of Node.
+
+:::tip
+
+If these tools seem intimidating, or if you run into difficulties, you can always [install Node through more traditional means](https://nodejs.org/en/download).
+
+:::
+
+Pulsar uses [Yarn](https://yarnpkg.com/) to manage Node dependencies. Once you’ve got the right version of Node set up, you can [install Yarn using these instructions](https://classic.yarnpkg.com/lang/en/docs/install/). (You want the “classic stable” version 1 of Yarn, not version 2.)
+
+To install the project’s Node dependencies, run
+
+```sh
+$ yarn install
+$ yarn build
+```
 
 ## Running in development mode
 
-Once you have a local copy of Pulsar cloned and built, you can then run Pulsar in development mode. But first, if you cloned Pulsar to somewhere other than <span class="platform-linux platform-mac">`~/github/pulsar`</span><span class="platform-win">`%USERPROFILE%\github\pulsar`</span>, you will need to set the `ATOM_DEV_RESOURCE_PATH` environment variable to point to the folder in which you cloned Pulsar.
+Once you have a local copy of Pulsar cloned and bootstrapped, you can then run Pulsar in development mode. But first, if you cloned Pulsar to somewhere other than <span class="platform-linux platform-mac">`~/github/pulsar`</span><span class="platform-win">`%USERPROFILE%\github\pulsar`</span>, you will need to set the `ATOM_DEV_RESOURCE_PATH` environment variable to point to the folder in which you cloned Pulsar.
 
 To run Pulsar in dev mode, use the `--dev` parameter from the terminal:
 
 ```sh
 $ pulsar --dev <path-to-open>
 ```
 
-There are a couple benefits of running Pulsar in Dev Mode:
+There are a couple benefits of running Pulsar in dev mode:
+
+1. When the `ATOM_DEV_RESOURCE_PATH` environment variable is set correctly, Pulsar is run using the source code from your local `pulsar-edit/pulsar` repository. This means you don’t have to rebuild after every change — just reload your current window with **Window: Reload**.
+
+    (Changes to “main process” code — basically any code that lives in `src/main-process` — will require a full relaunch of Pulsar, but most of Pulsar’s logic is in the renderer process.)
+
+2. Packages that exist in <span class="platform-linux platform-mac">`~/.pulsar/dev/packages`</span><span class="platform-win">`%USERPROFILE%\.pulsar\dev\packages`</span> are loaded instead of packages of the same name normally loaded from other locations.
+
+    This means that you can have development versions of packages you use loaded (via `pulsar -p link --dev [path-to-local-copy-of-a-package]`) but easily go back to the stable versions by launching without dev mode. This makes dev mode useful for developing packages even when `ATOM_DEV_RESOURCE_PATH` isn’t set.
 
-1. When the `ATOM_DEV_RESOURCE_PATH` environment variable is set correctly, Pulsar is run using the source code from your local `pulsar-edit/pulsar` repository. This means you don't have to rebuild after every change — just restart Pulsar.
-2. Packages that exist in <span class="platform-linux platform-mac">`~/.pulsar/dev/packages`</span><span class="platform-win">`%USERPROFILE%\.pulsar\dev\packages`</span> are loaded instead of packages of the same name normally loaded from other locations. This means that you can have development versions of packages you use loaded but easily go back to the stable versions by launching without dev mode.
-3. Packages that contain stylesheets, such as syntax themes, will have those stylesheets automatically reloaded by the {dev-live-reload} package. This does not live reload JavaScript or CoffeeScript files — you'll need to reload the window (`window:reload`) to see changes to those.
+3. Packages that contain stylesheets, such as syntax themes, will have those stylesheets automatically reloaded by the {dev-live-reload} package. This does not live reload JavaScript or CoffeeScript files — you’ll need to reload the window (`window:reload`) to see changes to those.
 
 ## Running Pulsar core tests locally
 
-In order to run Pulsar Core tests from the terminal, first be certain to set the `ATOM_DEV_RESOURCE_PATH` environment variable as mentioned above and then:
+### Within the terminal
+
+In order to run Pulsar core tests from the terminal, first be certain to set the `ATOM_DEV_RESOURCE_PATH` environment variable as mentioned above and then:
 
 ```sh
 $ cd <path-to-your-local-pulsar-repo>
 $ pulsar --test spec
 ```
+
+### Within Pulsar
+
+First, make sure to set `ATOM_DEV_RESOURCE_PATH`; then launch Pulsar and open a project whose root is the root of the Pulsar codebase. You may then run the package specs from within Pulsar by invoking the **Window: Run Package Specs** command. This will spawn a window that runs the specs and reports on their outcomes.
+
+## Running Pulsar builtin package tests locally
+
+### Within the terminal
+
+You can run a single package’s tests in similar fashion. For instance, to run the specs for the `autocomplete-plus` package, run the following from the root of the Pulsar project:
+
+```sh
+$ cd <path-to-your-local-pulsar-repo>
+$ pulsar --test packages/autocomplete-plus/spec
+```
+
+Since different packages may have configured different test runners, you are encouraged to run each builtin package’s specs separately for the best results. However, you may experiment with glob syntax if you wish to run several at once and are willing to tolerate unusual behavior.
+
+For instance, this will run all the specs for builtin language packages:
+
+```sh
+$ cd <path-to-your-local-pulsar-repo>
+$ pulsar --test packages/language-**/spec
+```
+
+### Within Pulsar
+
+You can run a single builtin package’s specs the same way you’d run specs for a package that _isn’t_ builtin: open the builtin package’s root directory in Pulsar as its own project, then invoke the **Window: Run Package Specs** command.

docs/contributing-to-pulsar/index.md

@@ -5,7 +5,7 @@ layout: summary.ejs
 
 While there are many ways to [customize the functionality of Pulsar](/customizing-pulsar), here we’ll dive into some advanced topics.
 
-As we've seen, a huge part of Pulsar is made up of bundled packages. If you wish to add some functionality to Pulsar, you have access to the same APIs and tools that the core features of Pulsar has.
+As we’ve seen, a huge part of Pulsar is made up of bundled packages. If you wish to add some functionality to Pulsar, you have access to the same APIs and tools that the core features of Pulsar has.
 
 From {tree-view} to {command-palette} to {find-and-replace}, even the most integral features of Pulsar are implemented as packages.
 

docs/contributing-to-pulsar/tools-of-the-trade.md

@@ -5,7 +5,7 @@ layout: doc.ejs
 
 Since all of Pulsar is implemented using web technologies, in this section we’ll assume you know web technologies such as JavaScript and CSS.
 
-While the majority of Pulsar is written in JavaScript, there are a few external modules that are still implemented in CoffeScript. All CoffeeScript that used to be present in the main Pulsar repository has been “decaffeinated” into JavaScript; you can [read more about that process here](https://github.com/pulsar-edit/.github/blob/main/guides/how-to-decaf.md).
+While the majority of Pulsar is written in JavaScript, there are a few external modules that are still implemented in CoffeeScript. All CoffeeScript that used to be present in the main Pulsar repository has been “decaffeinated” into JavaScript; you can [read more about that process here](https://github.com/pulsar-edit/.github/blob/main/guides/how-to-decaf.md).
 
 The only remnant of CoffeeScript that remains in Pulsar itself is CSON — a JSON-like notation based on CoffeeScript. We’ve kept CSON as the default file format for settings files (like your config file and keymap file) because it’s not as strict about delimiters and it allows comments.
 

docs/contributing-to-pulsar/using-ppm.md

@@ -1,37 +1,38 @@
 ---
-title: Using PPM (Pulsar Package Manager) (information may be out of date!)
+title: Using PPM (Pulsar Package Manager)
 layout: doc.ejs
 ---
 
-<!-- TODO: Needs updating. Not really accurate anymore. -->
+<!-- TODO: This language is rewritten to hedge a bit more just so we can remove the “information may be outdated!” scare text from the title. This still needs further investigation. -->
 
-`ppm` is used for installing and managing Pulsar's packages in much the same way that `apm` did on Atom. However at this point in the project there are a few hoops you have to jump through to get it to work correctly.
+`ppm` is used for installing and managing Pulsar’s packages in much the same way that `apm` did on Atom.
 
-After following the build instructions you will find the `ppm` binary at `pulsar/ppm/bin/apm` but by default Pulsar will be looking in the wrong place. There will also be issues relating to the Electron version which will prevent install from the package backend.
-
-To solve this a couple of environmental variables need to be exported.
+If you build Pulsar from source following the build instructions, you will find the `ppm` binary at `pulsar/ppm/bin/ppm`. This should be usable out of the box, but in some unusual scenarios you might find that you have to set some environment variables:
 
 ::: tabs#core-hacking
 
 @tab Linux
 
 ```sh
 export ATOM_HOME=/home/<user>/.pulsar
-export APM_PATH=/ppm/bin/apm
+export APM_PATH=<absolute path to your ppm binary>
 export ATOM_ELECTRON_VERSION=12.2.3
 ```
 
 @tab macOS
 
 ```sh
-TODO
+export ATOM_HOME=/Users/<user>/.pulsar
+export APM_PATH=<absolute path to your ppm binary>
+export ATOM_ELECTRON_VERSION=12.2.3
 ```
 
 @tab Windows
 
 ```
 set ATOM_HOME=C:\Users\<user>\.pulsar
-set APM_PATH=\ppm\bin\apm
+set APM_PATH=<absolute path to your ppm binary>
+set ATOM_ELECTRON_VERSION=12.2.3
 ```
 
 :::
@@ -46,5 +47,5 @@ git clone https://github.com/pulsar-edit/ide-java
 cd ide-java
 
 # from the directory where you are running pulsar source code
-<pulsar source>/ppm/bin/apm link
+<pulsar source>/ppm/bin/ppm link
 ```

docs/core-packages-and-features/autocomplete.md

@@ -3,7 +3,7 @@ title: Autocomplete
 layout: doc.ejs
 ---
 
-If you're still looking to save some typing time, Pulsar also ships with powerful autocompletion functionality.
+If you’re still looking to save some typing time, Pulsar also ships with powerful autocompletion functionality.
 
 The autocomplete system lets you view and insert possible completions in the editor using [[Tab]] or [[Enter]].
 
@@ -12,12 +12,12 @@ The autocomplete system lets you view and insert possible completions in the edi
 The simplest form of autocompletion will simply use words in the current file as completion candidates;
 
 By default, the autocomplete system will look through the current open file for
-strings that match what you're starting to type. But other packages can register themselves as providers of autocompletion data, thereby making autocompletion smarter.
+strings that match what you’re starting to type. But other packages can register themselves as providers of autocompletion data, thereby making autocompletion smarter.
 
 The autocompletion interface is implemented in the {autocomplete-plus} package. Several other core packages are present so that they can provide intelligent contextual suggestions to `autocomplete-plus`:
 
 * The core {autocomplete-html} package suggests tag names and attribute names.
 * The core {autocomplete-css} package suggests tag names, CSS property names, and contextually relevant values for properties.
 * The core {autocomplete-snippets} package suggests snippets whose prefixes match what has already been typed in the current word.
 
-Community packages — in particular packages that wrap language servers — can also act as “brains” for autocompletion. Pulsar’s package registry can show you [a list of packages](https://web.pulsar-edit.dev/packages?serviceType=provided&service=autocomplete.provider) that can supply data to `autocomplete-plus`.
+Community packages — in particular [packages that wrap language servers](/ide-features/) — can also act as “brains” for autocompletion. Pulsar’s package registry can show you [a list of packages](https://packages.pulsar-edit.dev/packages?serviceType=provided&service=autocomplete.provider) that can supply data to `autocomplete-plus`.