helix-editor · archseer · Mar 6, 2023 · Jan 14, 2023 · Jan 14, 2023 · Jan 14, 2023
diff --git a/README.md b/README.md
@@ -45,91 +45,10 @@ Note: Only certain languages have indentation definitions at the moment. Check
 
 # Installation
 
-Packages are available for various distributions (see [Installation docs](https://docs.helix-editor.com/install.html)).
-
-If you would like to build from source:
-
-```shell
-git clone https://github.com/helix-editor/helix
-cd helix
-cargo install --locked --path helix-term
-```
-
-This will install the `hx` binary to `$HOME/.cargo/bin` and build tree-sitter grammars in `./runtime/grammars`.
-
-Helix needs its runtime files so make sure to copy/symlink the `runtime/` directory into the
-config directory (for example `~/.config/helix/runtime` on Linux/macOS, or `%AppData%/helix/runtime` on Windows).
-
-| OS                   | Command                                          |
-| -------------------- | ------------------------------------------------ |
-| Windows (Cmd)        | `xcopy /e /i runtime %AppData%\helix\runtime`    |
-| Windows (PowerShell) | `xcopy /e /i runtime $Env:AppData\helix\runtime` |
-| Linux / macOS        | `ln -s $PWD/runtime ~/.config/helix/runtime`     |
-
-Starting with Windows Vista you can also create symbolic links on Windows. Note that this requires
-elevated privileges - i.e. PowerShell or Cmd must be run as administrator.
-
-**PowerShell:**
-
-```powershell
-New-Item -ItemType SymbolicLink -Target "runtime" -Path "$Env:AppData\helix\runtime"
-```
-
-**Cmd:**
-
-```cmd
-cd %appdata%\helix
-mklink /D runtime "<helix-repo>\runtime"
-```
-
-The runtime location can be overridden via the `HELIX_RUNTIME` environment variable.
-
-> NOTE: if `HELIX_RUNTIME` is set prior to calling `cargo install --locked --path helix-term`,
-> tree-sitter grammars will be built in `$HELIX_RUNTIME/grammars`.
-
-If you plan on keeping the repo locally, an alternative to copying/symlinking
-runtime files is to set `HELIX_RUNTIME=/path/to/helix/runtime`
-(`HELIX_RUNTIME=$PWD/runtime` if you're in the helix repo directory).
-
-Packages already solve this for you by wrapping the `hx` binary with a wrapper
-that sets the variable to the install dir.
-
-> NOTE: running via cargo also doesn't require setting explicit `HELIX_RUNTIME` path, it will automatically
-> detect the `runtime` directory in the project root.
-
-If you want to customize your `languages.toml` config,
-tree-sitter grammars may be manually fetched and built with `hx --grammar fetch` and `hx --grammar build`.
-
-In order to use LSP features like auto-complete, you will need to
-[install the appropriate Language Server](https://github.com/helix-editor/helix/wiki/How-to-install-the-default-language-servers)
-for a language.
+[Installation documentation](https://docs.helix-editor.com/install.html).
 
 [![Packaging status](https://repology.org/badge/vertical-allrepos/helix.svg)](https://repology.org/project/helix/versions)
 
-## Adding Helix to your desktop environment
-
-If installing from source, to use Helix in desktop environments that supports [XDG desktop menu](https://specifications.freedesktop.org/menu-spec/menu-spec-latest.html), including Gnome and KDE, copy the provided `.desktop` file to the correct folder:
-
-```bash
-cp contrib/Helix.desktop ~/.local/share/applications
-cp contrib/helix.png ~/.local/share/icons
-```
-
-To use another terminal than the default, you will need to modify the `.desktop` file. For example, to use `kitty`:
-
-```bash
-sed -i "s|Exec=hx %F|Exec=kitty hx %F|g" ~/.local/share/applications/Helix.desktop
-sed -i "s|Terminal=true|Terminal=false|g" ~/.local/share/applications/Helix.desktop
-```
-
-## macOS
-
-Helix can be installed on macOS through homebrew:
-
-```
-brew install helix
-```
-
 # Contributing
 
 Contributing guidelines can be found [here](./docs/CONTRIBUTING.md).

diff --git a/book/src/commands.md b/book/src/commands.md
@@ -1,5 +1,5 @@
 # Commands
 
-Command mode can be activated by pressing `:`, similar to Vim. Built-in commands:
+Command mode can be activated by pressing `:`. The built-in commands are:
 
 {{#include ./generated/typable-cmd.md}}
diff --git a/book/src/configuration.md b/book/src/configuration.md
@@ -2,10 +2,10 @@
 
 To override global configuration parameters, create a `config.toml` file located in your config directory:
 
-* Linux and Mac: `~/.config/helix/config.toml`
-* Windows: `%AppData%\helix\config.toml`
+- Linux and Mac: `~/.config/helix/config.toml`
+- Windows: `%AppData%\helix\config.toml`
 
-> Hint: You can easily open the config file by typing `:config-open` within Helix normal mode.
+> 💡 You can easily open the config file by typing `:config-open` within Helix normal mode.
 
 Example config:
 
@@ -25,36 +25,34 @@ select = "underline"
 hidden = false
 ```
 
-You may also specify a file to use for configuration with the `-c` or
-`--config` CLI argument: `hx -c path/to/custom-config.toml`.
-
-It is also possible to trigger configuration file reloading by sending the `USR1`
-signal to the helix process, e.g. via `pkill -USR1 hx`. This is only supported 
-on unix operating systems.
+You can use a custom configuration file by specifying it with the `-c` or
+`--config` command line argument, for example `hx -c path/to/custom-config.toml`.
+Additionally, you can reload the configuration file by sending the USR1
+signal to the Helix process on Unix operating systems, such as by using the command `pkill -USR1 hx`.
 
 ## Editor
 
 ### `[editor]` Section
 
 | Key | Description | Default |
 |--|--|---------|
-| `scrolloff` | Number of lines of padding around the edge of the screen when scrolling. | `5` |
-| `mouse` | Enable mouse mode. | `true` |
-| `middle-click-paste` | Middle click paste support. | `true` |
-| `scroll-lines` | Number of lines to scroll per scroll wheel step. | `3` |
-| `shell` | Shell to use when running external commands. | Unix: `["sh", "-c"]`<br/>Windows: `["cmd", "/C"]` |
-| `line-number` | Line number display: `absolute` simply shows each line's number, while `relative` shows the distance from the current line. When unfocused or in insert mode, `relative` will still show absolute line numbers. | `absolute` |
-| `cursorline` | Highlight all lines with a cursor. | `false` |
-| `cursorcolumn` | Highlight all columns with a cursor. | `false` |
+| `scrolloff` | Number of lines of padding around the edge of the screen when scrolling | `5` |
+| `mouse` | Enable mouse mode | `true` |
+| `middle-click-paste` | Middle click paste support | `true` |
+| `scroll-lines` | Number of lines to scroll per scroll wheel step | `3` |
+| `shell` | Shell to use when running external commands | Unix: `["sh", "-c"]`<br/>Windows: `["cmd", "/C"]` |
+| `line-number` | Line number display: `absolute` simply shows each line's number, while `relative` shows the distance from the current line. When unfocused or in insert mode, `relative` will still show absolute line numbers | `absolute` |
+| `cursorline` | Highlight all lines with a cursor | `false` |
+| `cursorcolumn` | Highlight all columns with a cursor | `false` |
 | `gutters` | Gutters to display: Available are `diagnostics` and `diff` and `line-numbers` and `spacer`, note that `diagnostics` also includes other features like breakpoints, 1-width padding will be inserted if gutters is non-empty | `["diagnostics", "spacer", "line-numbers", "spacer", "diff"]` |
-| `auto-completion` | Enable automatic pop up of auto-completion. | `true` |
-| `auto-format` | Enable automatic formatting on save. | `true` |
-| `auto-save` | Enable automatic saving on focus moving away from Helix. Requires [focus event support](https://github.com/helix-editor/helix/wiki/Terminal-Support) from your terminal. | `false` |
-| `idle-timeout` | Time in milliseconds since last keypress before idle timers trigger. Used for autocompletion, set to 0 for instant. | `400` |
+| `auto-completion` | Enable automatic pop up of auto-completion | `true` |
+| `auto-format` | Enable automatic formatting on save | `true` |
+| `auto-save` | Enable automatic saving on the focus moving away from Helix. Requires [focus event support](https://github.com/helix-editor/helix/wiki/Terminal-Support) from your terminal | `false` |
+| `idle-timeout` | Time in milliseconds since last keypress before idle timers trigger. Used for autocompletion, set to 0 for instant | `400` |
 | `completion-trigger-len` | The min-length of word under cursor to trigger autocompletion | `2` |
-| `auto-info` | Whether to display infoboxes | `true` |
-| `true-color` | Set to `true` to override automatic detection of terminal truecolor support in the event of a false negative. | `false` |
-| `rulers` | List of column positions at which to display the rulers. Can be overridden by language specific `rulers` in `languages.toml` file. | `[]` |
+| `auto-info` | Whether to display info boxes | `true` |
+| `true-color` | Set to `true` to override automatic detection of terminal truecolor support in the event of a false negative | `false` |
+| `rulers` | List of column positions at which to display the rulers. Can be overridden by language specific `rulers` in `languages.toml` file | `[]` |
 | `bufferline` | Renders a line at the top of the editor displaying open buffers. Can be `always`, `never` or `multiple` (only shown if more than one buffer is in use) | `never` |
 | `color-modes` | Whether to color the mode indicator with different colors depending on the mode itself | `false` |
 
@@ -123,10 +121,12 @@ The following statusline elements can be configured:
 
 ### `[editor.cursor-shape]` Section
 
-Defines the shape of cursor in each mode. Note that due to limitations
-of the terminal environment, only the primary cursor can change shape.
+Defines the shape of cursor in each mode.
 Valid values for these options are `block`, `bar`, `underline`, or `hidden`.
 
+> 💡 Due to limitations of the terminal environment, only the primary cursor can
+> change shape.
+
 | Key      | Description                                | Default |
 | ---      | -----------                                | ------- |
 | `normal` | Cursor shape in [normal mode][normal mode] | `block` |
@@ -139,25 +139,22 @@ Valid values for these options are `block`, `bar`, `underline`, or `hidden`.
 
 ### `[editor.file-picker]` Section
 
-Sets options for file picker and global search. All but the last key listed in
-the default file-picker configuration below are IgnoreOptions: whether hidden
-files and files listed within ignore files are ignored by (not visible in) the
-helix file picker and global search. There is also one other key, `max-depth`
-available, which is not defined by default.
+Set options for file picker and global search. Ignoring a file means it is
+not visible in the Helix file picker and global search.
 
 All git related options are only enabled in a git repository.
 
 | Key | Description | Default |
 |--|--|---------|
-|`hidden` | Enables ignoring hidden files. | true
+|`hidden` | Enables ignoring hidden files | true
 |`follow-links` | Follow symlinks instead of ignoring them | true
 |`deduplicate-links` | Ignore symlinks that point at files already shown in the picker | true
-|`parents` | Enables reading ignore files from parent directories. | true
-|`ignore` | Enables reading `.ignore` files. | true
-|`git-ignore` | Enables reading `.gitignore` files. | true
-|`git-global` | Enables reading global .gitignore, whose path is specified in git's config: `core.excludefile` option. | true
-|`git-exclude` | Enables reading `.git/info/exclude` files. | true
-|`max-depth` | Set with an integer value for maximum depth to recurse. | Defaults to `None`.
+|`parents` | Enables reading ignore files from parent directories | true
+|`ignore` | Enables reading `.ignore` files | true
+|`git-ignore` | Enables reading `.gitignore` files | true
+|`git-global` | Enables reading global `.gitignore`, whose path is specified in git's config: `core.excludefile` option | true
+|`git-exclude` | Enables reading `.git/info/exclude` files | true
+|`max-depth` | Set with an integer value for maximum depth to recurse | Defaults to `None`.
 
 ### `[editor.auto-pairs]` Section
 
@@ -209,7 +206,7 @@ Search specific options.
 
 | Key | Description | Default |
 |--|--|---------|
-| `smart-case` | Enable smart case regex searching (case insensitive unless pattern contains upper case characters) | `true` |
+| `smart-case` | Enable smart case regex searching (case-insensitive unless pattern contains upper case characters) | `true` |
 | `wrap-around`| Whether the search should wrap after depleting the matches | `true` |
 
 ### `[editor.whitespace]` Section
@@ -218,7 +215,7 @@ Options for rendering whitespace with visible characters. Use `:set whitespace.r
 
 | Key | Description | Default |
 |-----|-------------|---------|
-| `render` | Whether to render whitespace. May either be `"all"` or `"none"`, or a table with sub-keys `space`, `nbsp`, `tab`, and `newline`. | `"none"` |
+| `render` | Whether to render whitespace. May either be `"all"` or `"none"`, or a table with sub-keys `space`, `nbsp`, `tab`, and `newline` | `"none"` |
 | `characters` | Literal characters to use when rendering whitespace. Sub-keys may be any of `tab`, `space`, `nbsp`, `newline` or `tabpad` | See example below |
 
 Example
@@ -246,7 +243,7 @@ Options for rendering vertical indent guides.
 
 | Key           | Description                                             | Default |
 | ---           | ---                                                     | ---     |
-| `render`      | Whether to render indent guides.                        | `false` |
+| `render`      | Whether to render indent guides                         | `false` |
 | `character`   | Literal character to use for rendering the indent guide | `│`     |
 | `skip-levels` | Number of indent levels to skip                         | `0`     |
 
@@ -271,7 +268,7 @@ gutters = ["diff", "diagnostics", "line-numbers", "spacer"]
 
 To customize the behavior of gutters, the `[editor.gutters]` section must
 be used. This section contains top level settings, as well as settings for
-specific gutter components as sub-sections.
+specific gutter components as subsections.
 
 | Key      | Description                    | Default                                                       |
 | ---      | ---                            | ---                                                           |
@@ -313,13 +310,13 @@ Currently unused
 
 ### `[editor.soft-wrap]` Section
 
-Options for soft wrapping lines that exceed the view width
+Options for soft wrapping lines that exceed the view width:
 
 | Key                 | Description                                                  | Default |
 | ---                 | ---                                                          | ---     |
-| `enable`            | Whether soft wrapping is enabled.                            | `false` |
-| `max-wrap`          | Maximum free space left at the end of the line.              | `20`    |
-| `max-indent-retain` | Maximum indentation to carry over when soft wrapping a line. | `40`    |
+| `enable`            | Whether soft wrapping is enabled                             | `false` |
+| `max-wrap`          | Maximum free space left at the end of the line               | `20`    |
+| `max-indent-retain` | Maximum indentation to carry over when soft wrapping a line  | `40`    |
 | `wrap-indicator`    | Text inserted before soft wrapped lines, highlighted with `ui.virtual.wrap` | `↪ `    |
 
 Example:

diff --git a/book/src/guides/README.md b/book/src/guides/README.md
@@ -1,4 +1,4 @@
 # Guides
 
 This section contains guides for adding new language server configurations,
-tree-sitter grammars, textobject queries, etc.
+tree-sitter grammars, textobject queries, and other similar items.
diff --git a/book/src/guides/adding_languages.md b/book/src/guides/adding_languages.md
@@ -1,45 +1,52 @@
-# Adding languages
+# Adding new languages to Helix
+
+In order to add a new language to Helix, you will need to follow the steps
+below.
 
 ## Language configuration
 
-To add a new language, you need to add a `[[language]]` entry to the
-`languages.toml` (see the [language configuration section]).
+1. Add a new `[[language]]` entry in the `languages.toml` file and provide the
+   necessary configuration for the new language. For more information on
+   language configuration, refer to the
+   [language configuration section](../languages.md) of the documentation.
+2. If you are adding a new language or updating an existing language server
+   configuration, run the command `cargo xtask docgen` to update the
+   [Language Support](../lang-support.md) documentation.
 
-When adding a new language or Language Server configuration for an existing
-language, run `cargo xtask docgen` to add the new configuration to the
-[Language Support][lang-support] docs before creating a pull request.
-When adding a Language Server configuration, be sure to update the
-[Language Server Wiki][install-lsp-wiki] with installation notes.
+> 💡 If you are adding a new Language Server configuration, make sure to update
+> the
+> [Language Server Wiki](https://github.com/helix-editor/helix/wiki/How-to-install-the-default-language-servers)
+> with the installation instructions.
 
 ## Grammar configuration
 
-If a tree-sitter grammar is available for the language, add a new `[[grammar]]`
-entry to `languages.toml`.
-
-You may use the `source.path` key rather than `source.git` with an absolute path
-to a locally available grammar for testing, but switch to `source.git` before
-submitting a pull request.
+1. If a tree-sitter grammar is available for the new language, add a new
+   `[[grammar]]` entry to the `languages.toml` file.
+2. If you are testing the grammar locally, you can use the `source.path` key
+   with an absolute path to the grammar. However, before submitting a pull
+   request, make sure to switch to using `source.git`.
 
 ## Queries
 
-For a language to have syntax-highlighting and indentation among
-other things, you have to add queries. Add a directory for your
-language with the path `runtime/queries/<name>/`. The tree-sitter
-[website](https://tree-sitter.github.io/tree-sitter/syntax-highlighting#queries)
-gives more info on how to write queries.
-
-> NOTE: When evaluating queries, the first matching query takes
-precedence, which is different from other editors like Neovim where
-the last matching query supersedes the ones before it. See
-[this issue][neovim-query-precedence] for an example.
-
-## Common Issues
-
-- If you get errors when running after switching branches, you may have to update the tree-sitter grammars. Run `hx --grammar fetch` to fetch the grammars and `hx --grammar build` to build any out-of-date grammars.
-
-- If a parser is segfaulting or you want to remove the parser, make sure to remove the compiled parser in `runtime/grammar/<name>.so`
-
-[language configuration section]: ../languages.md
-[neovim-query-precedence]: https://github.com/helix-editor/helix/pull/1170#issuecomment-997294090
-[install-lsp-wiki]: https://github.com/helix-editor/helix/wiki/How-to-install-the-default-language-servers
-[lang-support]: ../lang-support.md
+1. In order to provide syntax highlighting and indentation for the new language,
+   you will need to add queries.
+2. Create a new directory for the language with the path
+   `runtime/queries/<name>/`.
+3. Refer to the
+   [tree-sitter website](https://tree-sitter.github.io/tree-sitter/syntax-highlighting#queries)
+   for more information on writing queries.
+
+> 💡 In Helix, the first matching query takes precedence when evaluating
+> queries, which is different from other editors such as Neovim where the last
+> matching query supersedes the ones before it. See
+> [this issue](https://github.com/helix-editor/helix/pull/1170#issuecomment-997294090)
+> for an example.
+
+## Common issues
+
+- If you encounter errors when running Helix after switching branches, you may
+  need to update the tree-sitter grammars. Run the command `hx --grammar fetch`
+  to fetch the grammars and `hx --grammar build` to build any out-of-date
+  grammars.
+- If a parser is causing a segfault, or you want to remove it, make sure to
+  remove the compiled parser located at `runtime/grammar/<name>.so`.