Merge pull request #4 from savetheclocktower/apd-misc-2

Miscellaneous fixes

docs/customizing-pulsar/customizing-keybindings.md

@@ -3,10 +3,7 @@ title: Customizing keybindings
 layout: doc.ejs
 ---
 
-Pulsar keymaps work similarly to stylesheets. Just as stylesheets use selectors
-to apply styles to elements, Pulsar keymaps use selectors to associate key
-combinations with events in specific contexts. Here's a small example, excerpted
-from Pulsar's built-in keymap:
+Pulsar keymaps work similarly to stylesheets. Just as stylesheets use selectors to apply styles to elements, Pulsar keymaps use selectors to associate key combinations with events in specific contexts. Here's a small example, excerpted from Pulsar's built-in keymap:
 
 ```coffee
 'atom-text-editor':
@@ -16,14 +13,14 @@ from Pulsar's built-in keymap:
   'enter': 'core:confirm'
 ```
 
-This keymap defines the meaning of [[Enter]] in two different contexts.
-In a normal editor, pressing [[Enter]] triggers the `editor:newline`
-command, which causes the editor to insert a newline. But if the same keystroke
-occurs inside a select list's mini-editor, it instead triggers the
-`core:confirm` command based on the binding in the more-specific selector.
+This keymap defines the meaning of [[Enter]] in two different contexts. In a normal editor, pressing [[Enter]] triggers the `editor:newline` command, which causes the editor to insert a newline. But if the same keystroke occurs inside a “mini-editor” — the component that handles nearly all single-line text fields in Pusar — it instead triggers the `core:confirm` command based on the binding in the more-specific selector.
 
-By default, `keymap.cson` is loaded when Pulsar is started. It will always be loaded last, giving you the chance to override bindings that are defined by Pulsar's core keymaps or third-party packages. You can open this file in an editor from the <span class="platform-linux">_Edit > Keymap_</span><span class="platform-mac">_Pulsar > Keymap…_</span><span class="platform-win">_File > Keymap_</span> menu item.
+When Pulsar starts, it loads your personal keymap from the `keymap.cson` file in your <span class="platform-linux platform-mac">`~/.pulsar`</span><span class="platform-win">`%USERPROFILE%\.pulsar`</span> folder. It will always be loaded last, giving you the chance to override bindings that are defined by Pulsar's core keymaps or third-party packages. You can open this file in an editor from the <span class="platform-linux">_Edit > Keymap_</span><span class="platform-mac">_Pulsar > Keymap…_</span><span class="platform-win">_File > Keymap_</span> menu item.
 
 You can see all the keybindings that are currently configured in your installation of Pulsar in the Keybindings tab in the Settings View.
 
-If you run into problems with keybindings, the Keybinding Resolver is a huge help. It can be opened with the <kbd class="platform-linux platform-win">Ctrl+.</kbd> <kbd class="platform-mac">Cmd+.</kbd> key combination. It will show you what keys Pulsar saw you press and what command Pulsar executed because of that combination.
+If you run into problems with keybindings, the **keybinding resolver** is a huge help. It can be opened with the <kbd class="platform-linux platform-win">Ctrl+.</kbd> <kbd class="platform-mac">Cmd+.</kbd> key combination. It will show you what keys Pulsar saw you press and what command Pulsar executed because of that combination.
+
+![keybinding resolver screenshot](/img/atom/keybinding-resolver-2.png "keybinding resolver screenshot")
+
+The keybinding resolver is provided by the {keybinding-resolver} package.

docs/customizing-pulsar/customizing-language-recognition.md

@@ -3,7 +3,7 @@ title: Customizing language recognition
 layout: doc.ejs
 ---
 
-If you want Pulsar to always recognize certain file types as a specific grammar, you'll need to manually edit your `config.cson` file. You can open it using the _Application: Open Your Config_ command from the Command Palette. For example, if you wanted to add the `foo` extension to the CoffeeScript language, you could add this to your configuration file under the `*.core` section:
+If you want Pulsar to always recognize certain file types as a specific grammar, you'll need to manually edit your `config.cson` file. You can open it using the **Application: Open Your Config** command from the Command Palette. For example, if you wanted to add the `foo` extension to the CoffeeScript language, you could add this to your configuration file under the `*.core` section:
 
 ```coffee
 '*':

docs/customizing-pulsar/global-configuration-settings.md

@@ -3,7 +3,7 @@ title: Global configuration settings
 layout: doc.ejs
 ---
 
-Pulsar loads configuration settings from the `config.cson` file in your <span class="platform-linux platform-mac">`~/.pulsar`</span><span class="platform-win">`%USERPROFILE%\.pulsar`</span>.
+Pulsar loads configuration settings from the `config.cson` file in your <span class="platform-linux platform-mac">`~/.pulsar`</span><span class="platform-win">`%USERPROFILE%\.pulsar`</span> folder.
 
 ```coffee
 '*':
@@ -13,10 +13,12 @@ Pulsar loads configuration settings from the `config.cson` file in your <span cl
     'fontSize': 18
 ```
 
-The configuration is grouped into global settings under the `*` key and language-specific settings under scope named keys like `.python.source` or `.html.text`. Underneath that, you'll find configuration settings grouped by package name or one of the two core namespaces: `core` or `editor`.
+The configuration is grouped into global settings under the `*` key and language-specific settings [under scope-named keys](../language-specific-configuration-settings/) like `.python.source` or `.html.text`. Underneath that, you'll find configuration settings grouped by package name or one of the two core namespaces: `core` or `editor`.
 
 You can open this file in an editor from the <span class="platform-linux">_Edit > Config_</span><span class="platform-mac">_Pulsar > Config…_</span><span class="platform-win">_File > Config_</span> menu item.
 
+For global configuration settings, you may either edit this file directly or use the UI provided by the `settings-view` package (available via the <span class="platform-linux">_Edit > Preferences_</span> <span class="platform-mac">_Pulsar > Preferences_</span> <span class="platform-win">_File > Preferences_</span> menu). If you make changes to your settings via the `settings-view` UI, they will propagate to your `config.cson` file immediately.
+
 ## Configuration key reference
 
 - `core`

docs/customizing-pulsar/language-specific-configuration-settings.md

@@ -3,9 +3,7 @@ title: Language-specific configuration settings
 layout: doc.ejs
 ---
 
-Some settings can be specified differently for different file
-types. For example, you may want Pulsar to soft-wrap Markdown files, use
-two-space tabs for Ruby files, and use four-space tabs for Python files.
+Some settings can be specified differently for different file types. For example, you may want Pulsar to soft-wrap Markdown files, use two-space tabs for Ruby files, and use four-space tabs for Python files.
 
 Many of the settings in the `editor` namespace can be scoped to an editor’s language:
 
@@ -36,7 +34,7 @@ Most other language-specific settings cannot be configured in the UI, but you ca
 
 To open your `config.cson`, run the **Application: Open Your Config** setting or press <kbd class="platform-linux platform-win">Ctrl+Shift+P</kbd><kbd class="platform-mac">Cmd+Shift+P</kbd>.
 
-Global settings are under the `*` key, and each language can have its own top-level key. This key is the language's scope. Language-specific settings take precedence over anything set in the global section for that language only.
+Global settings are under the `*` key, and each language can have its own top-level key. This key is the language’s _scope_. Language-specific settings take precedence over anything set in the global section for that language only.
 
 ```coffee
 '*': # all languages unless overridden
@@ -58,7 +56,7 @@ Global settings are under the `*` key, and each language can have its own top-le
 ```
 
 :::tip
-When you save your `config.cson`, you might see its contents change slightly. For instance, the keys above will be “normalized” to `.gfm.source`, `.ruby.source`, and `.python.source` (with the segments of each scope arranged alphabetically). This is normal.
+When you save your `config.cson`, you might see its contents change slightly. For instance, the keys above will be “normalized” to `.gfm.source`, `.ruby.source`, and `.python.source` (with the segments of each scope ordered alphabetically). This is normal.
 :::
 
 ## Finding a language’s scope name

docs/customizing-pulsar/style-tweaks.md

@@ -5,23 +5,66 @@ layout: doc.ejs
 
 If you want to apply quick-and-dirty personal styling changes without creating an entire theme that you intend to publish, you can add styles to the `styles.less` file in your <span class="platform-linux platform-mac">`~/.pulsar`</span><span class="platform-win">`%USERPROFILE%\.pulsar`</span> directory. You can open this file in an editor from the <span class="platform-linux">_Edit > Stylesheet_</span><span class="platform-mac">_Pulsar > Stylesheet…_</span><span class="platform-win">_File > Stylesheet_</span> menu.
 
-For example, to change the colors of the Status Bar, you could add the following rule to your `styles.less` file:
+For example, to change the colors of the status bar, you could add the following rule to your `styles.less` file:
 
 ```css
 .status-bar {
-	color: white;
-	background-color: black;
+  color: white;
+  background-color: black;
 }
 ```
 
+::: tip Tip
+[Less](https://lesscss.org) is a basic CSS preprocessor that offers some useful features like variables, functions, and mixins. You can read more about its features in [this in-depth guide](https://lesscss.org/features/).
+
+If you prefer to use CSS instead, you’re in luck: all CSS syntax is valid in a Less stylesheet. Write it as you ordinarily would.
+:::
+
+## Using developer tools to discover class names
+
 The easiest way to see what classes are available to style is to inspect the DOM manually via the Developer Tools. To go over the Developer Tools in great detail, [refer to its documentation](/debugging-pulsar/check-for-errors-in-developer-tools/), but for now let's take a quick look. You can open the Developer Tools by pressing <kbd class="platform-linux platform-win">Ctrl+Shift+I</kbd> <kbd class="platform-mac">Alt+Cmd+I</kbd>, which will bring up the Chromium Developer Tools panel.
 
-![Developer Tools](/img/atom/devtools.png "Developer Tools")
+![Developer Tools](/img/atom/devtools-inspect-element.png "Developer Tools")
 
 With the Developer Tools, you can inspect all the elements in Pulsar. If you want to update the style of something, you can figure out what classes it has and add a Less rule to your stylesheet to modify it.
 
-::: tip Tip
-[Less](https://lesscss.org) is a basic CSS preprocessor that offers some useful features like variables, functions, and mixins. You can read more about its features in [this in-depth guide](https://lesscss.org/features/).
+## Advanced customization with variables
 
-If you prefer to use CSS instead, you’re in luck: all CSS syntax is valid in a Less stylesheet. Write it as you ordinarily would.
-:::
+[Syntax and UI themes in Pulsar](/developing-for-pulsar/developing-a-theme/) define variables that can be used by other stylesheets in Pulsar — including your user stylesheet.
+
+Suppose you want to customize the color of a variable in Python. You can use the developer tools to inspect a Python variable to discover the right selector to use for customizing its appearance; then you can use a variable in your user stylesheet as follows:
+
+```less
+@import 'syntax-variables';
+
+.syntax--source.syntax--python {
+  .syntax--variable {
+    // You could make it plain…
+    color: @syntax-text-color !important;
+    // …or color it like a string…
+    color: @syntax-color-string !important;
+    // …or like a keyword…
+    color: @syntax-color-keyword !important;
+    // …or something else.
+    // (`!important` may or may not be necessary here, depending on how your
+    // syntax theme defines its rules.)
+  }
+}
+```
+
+If we hard-coded a color value here, we’d probably want to change the value if we switched syntax themes in the future. Instead, we can use one of the variables that syntax themes must define; that way the rule will work no matter which syntax theme is active.
+
+Here’s [the full list of syntax variables](https://github.com/pulsar-edit/pulsar/blob/master/static/variables/syntax-variables.less) you can rely on.
+
+There is a similar set of variables you can use when customizing the UI:
+
+```less
+@import 'ui-variables';
+
+// When a file has unsaved changes, make the tab text yellow.
+li.tab.modified {
+  color: @text-color-warning;
+}
+```
+
+Here’s [the full set of UI variables](https://github.com/pulsar-edit/pulsar/blob/master/static/variables/ui-variables.less) you can rely on.

docs/customizing-pulsar/the-init-file.md

@@ -6,7 +6,7 @@ layout: doc.ejs
 ::: info
 The default init file for Pulsar has been changed from the previous CoffeeScript `init.coffee` file used by Atom to JavaScript. You are still able to use an old `init.coffee` file — and even create a new one for use instead of `init.js`.
 
-Should you wish to reference the specific version of this document for CoffeeScript, you can find it in the [Atom Archive](TODO).
+Should you wish to reference the specific version of this document for CoffeeScript, you can find it in [the Wayback Machine’s archived version of the Atom Flight Manual](https://web.archive.org/web/20200812183209/https://flight-manual.atom.io/hacking-atom/sections/the-init-file/).
 :::
 
 When Pulsar finishes loading, it will evaluate `init.js` in your <span class="platfom-linux platform-mac">`~/.pulsar`</span> <span class="platform-win">`%USERPROFILE%\.pulsar`</span> directory, giving you a chance to run JavaScript code to make customizations. Code in this file has full access to [Pulsar’s API](/api/pulsar/latest). If customizations become extensive, consider creating a package, which we will cover in [Package: Word count](/developing-for-pulsar/package-word-count/).
@@ -43,7 +43,7 @@ That’s because there’s no way to undo the side effects of the _previous_ exe
 You can reload pulsar with the **Window: Reload** command.
 :::
 
-Once you’ve saved your init file and reloaded Pulsar, use the [command palette](../../getting-started#command-palette) to execute the new command, **Markdown: Paste as Link**, by name. And if you'd like to trigger the command via a keyboard shortcut, you can define a [keybinding for the command](../../using-pulsar#customizing-keybindings).
+Once you’ve saved your init file and reloaded Pulsar, use the [command palette](../../using-pulsar/basics/#command-palette) to execute the new command, **Markdown: Paste As Link**, by name. And if you'd like to trigger the command via a keyboard shortcut, you can define a [keybinding for the command](../customizing-keybindings).
 
 :::tip
 Since a command name takes the format `foo:bar`, where `foo` is typically the package name, you might wonder what value to use before the colon if you define commands in your init file.

docs/developing-for-pulsar/creating-a-fork-of-a-core-package.md

@@ -7,7 +7,7 @@ Several of Pulsar's core packages are maintained in the [`packages` directory of
 
 ::: tip Tip
 
-In most cases, we recommend [generating a brand-new package](#package-generator) or a [brand-new theme](#creating-a-syntax-theme) as the starting point for your creation. The guide below applies only to situations where you want to create a package that closely resembles a core Pulsar package.
+In most cases, we recommend [generating a brand-new package](../developing-a-package/#package-generator) or a [brand-new theme](../developing-a-theme/#creating-a-syntax-theme) as the starting point for your creation. The guide below applies only to situations where you want to create a package that closely resembles a core Pulsar package.
 
 :::
 
@@ -70,7 +70,7 @@ $ git commit -am "Apply initial customizations"
 
 9. Follow the instructions in the github.com UI to push your code to your new online repository.
 
-10. Follow the steps in the [Publishing guide](#publishing) to publish your new package.
+10. Follow the steps in the [Publishing guide](../publishing/) to publish your new package.
 
 ## Merging upstream changes into your package
 

docs/developing-for-pulsar/creating-a-grammar-legacy-tree-sitter.md

@@ -79,7 +79,7 @@ parser: 'tree-sitter-mylanguage'
   This string will be passed directly to [`require()`](https://nodejs.org/api/modules.html#modules_require)
   in order to load the parser.
 - `type` - This should have the value `tree-sitter` to indicate to Pulsar that
-  this is a Tree-sitter grammar and not a [TextMate grammar](#creating-a-legacy-textmate-grammar).
+  this is a Tree-sitter grammar and not a [TextMate grammar](../creating-a-grammar-textmate/).
 
 ## Language recognition
 

docs/developing-for-pulsar/creating-a-grammar-modern-tree-sitter.md

@@ -166,7 +166,7 @@ The HTML classes that Pulsar uses for syntax highlighting do not correspond dire
 Here is a simple example:
 
 ```scm
-(call_expression;
+(call_expression
   (identifier) @support.other.function)
 ```
 
@@ -188,7 +188,7 @@ Tree-sitter supports additional matching criteria for queries called _predicates
 
 We’re using the built-in `#match?` predicate, along with a regular expression, to search the text within the `comment` node. Our regexes are anchored to the beginning of the string and test whether the opening delimiter signifies a block comment (`/* like this */`) or a line comment (`// like this`). In the block comment’s case, we don’t have to attempt to match the ending (`*/`) delimiter — we _know_ it must be present, or else the Tree-sitter parser wouldn’t have classified it as a `comment` node in the first place.
 
-Unfortunately, there aren’t many built-in predicates in `web-tree-sitter` alongside `#match?` and `#eq?` (which tests for _exact_ equality). But the ones that are present — `#set!`, `#is?`, and `#is-not` — allow us to associate arbitrary key/value pairs with a specific capture. Pulsar uses these to define its own _custom_ predicates.
+Unfortunately, there aren’t many built-in predicates in `web-tree-sitter` alongside `#match?` and `#eq?` (which tests for _exact_ equality). But the ones that are present — `#set!`, `#is?`, and `#is-not?` — allow us to associate arbitrary key/value pairs with a specific capture. Pulsar uses these to define its own _custom_ predicates.
 
 For instance, you may want to highlight things differently based on their position among siblings:
 

docs/developing-for-pulsar/developing-a-package.md

@@ -148,7 +148,7 @@ Your package's top-level module can implement the following basic methods:
   considered loading until the promise resolves (or rejects).
 - `initialize(state)`: This **optional** method is similar to `activate()` but
   is called earlier. Whereas activation occurs after the workspace has been
-  deserialized (and can therefore happen after [your package's deserializers](../../behind-pulsar#serialization-methods)
+  deserialized (and can therefore happen after [your package's deserializers](/infrastructure/serialization-in-pulsar/#serialization-methods)
   have been called), `initialize()` is guaranteed to be called before everything.
   Use `activate()` if you want to be sure that the workspace is ready; use
   `initialize()` if you need to do some setup prior to your deserializers or

docs/developing-for-pulsar/developing-a-theme.md

@@ -19,7 +19,7 @@ Themes are pretty straightforward, but it’s still helpful to be familiar with
   variables. If you aren't familiar with its syntax, take a few minutes to
   [familiarize yourself](https://speakerdeck.com/danmatthews/less-css).
 - You may also want to review the concept of a `package.json` (as covered in
-  [Pulsar `package.json`](#package-json)). This file is used to help distribute your theme to Pulsar users.
+  [Pulsar `package.json`](../developing-a-package/#package.json)). This file is used to help distribute your theme to Pulsar users.
 - Your theme's `package.json` must contain a `theme` key with a value of `ui`
   or `syntax` for Pulsar to recognize and load it as a theme.
 - You can find existing themes to install or fork in