Merge pull request #23 from pulsar-edit/misc-fixes-part-6

Miscellaneous fixes, part 6 (plus an “IDE features” section)

Author: savetheclocktower

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

@@ -20,4 +20,4 @@ The autocompletion interface is implemented in the {autocomplete-plus} package.
 * 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://web.pulsar-edit.dev/packages?serviceType=provided&service=autocomplete.provider) that can supply data to `autocomplete-plus`.

docs/core-packages-and-features/core-packages-and-features.11tydata.json

@@ -18,7 +18,7 @@
     },
     {
       "text": "Version control",
-      "link": "/core-packages-and-features/version-control-in-pulsar",
+      "link": "/core-packages-and-features/version-control",
       "summary": "Keep a history of your files’ changes."
     },
     {

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

@@ -56,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 ordered alphabetically). This is normal.
+When you save your `config.cson`, you might see its contents change slightly — or it might happen at some point in the future. For instance, the keys above will generally 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/developing-for-pulsar/package-modifying-text.md

@@ -3,10 +3,7 @@ title: "Package: Modifying text"
 layout: doc.ejs
 ---
 
-This section will guide you though creating a
-simple command that replaces the selected text with [ascii art](https://en.wikipedia.org/wiki/ASCII_art).
-When you run our new command with the word "cool" selected, it will be replaced
-with:
+This section will guide you though creating a simple command that replaces the selected text with [ascii art](https://en.wikipedia.org/wiki/ASCII_art). When you run our new command with the word "cool" selected, it will be replaced with:
 
 <pre>
                                      o888

docs/docs.11tydata.json

@@ -21,6 +21,11 @@
       "link": "/customizing-pulsar",
       "summary": "Learn about how to customize Pulsar’s keybindings, per-language settings, and styles."
     },
+    {
+      "text": "IDE features",
+      "link": "/ide-features",
+      "summary": "Hook Pulsar up to “brain” packages that make it behave more like a language-specific IDE."
+    },
     {
       "text": "Developing for Pulsar",
       "link": "/developing-for-pulsar",
@@ -50,11 +55,6 @@
       "text": "APIs",
       "link": "/api",
       "summary": "Read reference documentation for our APIs: Pulsar’s own API and that of the package repository."
-    },
-    {
-      "text": "IDE Features",
-      "link": "/ide-features",
-      "summary": "Hook Pulsar up to ‘brain’ packages that make it behave more like a language-specific IDE."
     }
   ]
 

docs/getting-started/installing-pulsar.md

@@ -117,7 +117,7 @@ Pulsar on Windows supports a standard installation as well as running Pulsar in
 
 To install Pulsar regularly, download the `Setup` file, and double click to run. During the installation process, you’ll be able to choose either the default user install (just the current user) or a machine install (all users of the machine). A user install is recommended, but either one will work, though a machine install will require administrative privileges.
 
-You’ll be asked whether the folders that contain the `pulsar` and `ppm` binaries should be added to your `PATH`. This is recommended; it will make it easier to [launch Pulsar from a terminal](http://localhost:8081/getting-started/terminal-commands/).
+You’ll be asked whether the folders that contain the `pulsar` and `ppm` binaries should be added to your `PATH`. This is recommended; it will make it easier to [launch Pulsar from a terminal](/getting-started/terminal-commands/).
 
 :::note
 

docs/ide-features/builtin-packages.md

@@ -0,0 +1,65 @@
+---
+title: "IDE features provided by builtin packages"
+layout: doc.ejs
+---
+
+So far we’ve told you how to install an IDE package for a given language — the “brain” that knows how to deliver lots of IDE features. But brains can’t do anything by themselves. What does the brain talk to? How do you use the features themselves?
+
+For various reasons, some of these IDE features are provided by built-in packages, and others require additional community packages to enable. First, let’s talk about the built-in packages, and the features you get for free without further installation.
+
+::: tip
+
+If any of the features described below do not work, revisit the README file for your IDE package and ensure you’ve configured it properly. See the [troubleshooting](../troubleshooting) page for more information.
+
+:::
+
+## Autocompletion
+
+We’ve learned that autocompletion is provided by the {autocomplete-plus} package. IDE packages use the `autocomplete.provider` [service](/infrastructure/interacting-with-other-packages-via-services/) to supply contextual autocompletion suggestions to the user.
+
+Even where other autocompletion providers exist — like the built-in {autocomplete-html} and {autocomplete-css} — the autocompletion you get from an IDE package is likely to be more contextually aware and more useful.
+
+<figure>
+  <div>
+    <img src="/img/atom/autocomplete-plus-language-server.png" alt="autocompletion via pulsar-ide-typescript">
+  </div>
+  <figcaption><p>In this example, <code>pulsar-ide-typescript</code> is able to offer us a contextual completion for this parameter type.</p></figcaption>
+</figure>
+
+
+## Symbol resolution
+
+We briefly mentioned how you can [navigate through files by symbol](/using-pulsar/movement/#navigating-by-symbols). Those symbols could be a number of things depending on the kind of file: method names, CSS selectors, or Markdown heading names, to list a few examples.
+
+This functionality is supplied by the built-in {symbols-view} package. Even without an IDE package, Pulsar allows you to navigate by symbols in most languages for the current file. (Since the file is already open, this isn’t hard!) But `symbols-view` also has the ability to jump to a symbol in a _different_ file, but not automatically; it needs something to tell it what those symbols are. A language server can do that very thing!
+
+:::tip
+
+Old IDE packages written for Atom don’t have this feature! You’ll need an IDE provider package _specifically written for Pulsar_. Pick one [from the list](../getting-started) or ensure it starts with `pulsar-ide-` instead of just `ide-`.
+
+:::
+
+An IDE package is especially useful for symbol resolution and lets you search for symbols on a _project-wide_ basis. For instance, the **Symbols View: Toggle Project Symbols** command (<kbd class="platform-mac">Cmd+Shift+R</kbd><kbd class="platform-linux platform-win">Ctrl+Shift+R</kbd> by default) will open a palette into which you can type the name of a symbol that may exist anywhere in your project.
+
+<figure>
+  <video controls>
+    <source src="/img/atom/symbols-view-toggle-project-symbols.webm" type="video/webm">
+    <a href=/img/atom/symbols-view-toggle-project-symbols.webm">Download as WebM</a>
+  </video>
+  <figcaption><p><strong>Symbols View: Toggle Project Symbols</strong> lets you search for symbols across the entire project.</p></figcaption>
+</figure>
+
+
+Even more powerful is the ability to jump to where a symbol is defined. Place your cursor inside the name of a function, then invoke the **Symbols View: Go To Declaration** command (<kbd class="platform-mac">Cmd+Alt+Down</kbd><kbd class="platform-linux platform-win">Ctrl+Alt+Shift+Down</kbd> by default) to jump to the declaration of that function!
+
+But this isn’t a one-way trip: when you’re done consulting the function definition, you can invoke **Symbols View: Return From Declaration** (<kbd class="platform-mac">Cmd+Alt+Up</kbd><kbd class="platform-linux platform-win">Ctrl+Alt+Shift+Up</kbd> by default) to return to your previous location.
+
+<figure>
+  <video controls>
+    <source src="/img/atom/symbols-view-go-to-declaration.webm" type="video/webm">
+    <a href=/img/atom/symbols-view-go-to-declaration.webm">Download as WebM</a>
+  </video>
+  <figcaption><p><strong>Symbols View: Go To Declaration</strong> lets you jump to the place where a symbol is defined, no matter where it is in your project. <strong>Symbols View: Return From Declaration</strong> will return you to your original position.</p></figcaption>
+</figure>
+
+The list of locations you jump _from_ functions like a web browser’s history stack. For instance, you can jump three definitions deep, then invoke **Symbols View: Return From Declaration** three times in a row to go back to where you started.