Rewrite and refactor all documentation (#5534)

* Rewrite and refactor all documentation

* Rewrite and refactor the guides

* update runtime directory instructions for windows

* Update the Ubuntu 3rd party repo section with 22.10

* Merge from upstream

* Rewrite and refactor all documentation

* Apply suggestions from code review

Apply the suggestions that can be committed from the GitHub web interface.

Co-authored-by: Michael Davis <mcarsondavis@gmail.com>

* Add Windows themes folder

Co-authored-by: digidoor <37601466+digidoor@users.noreply.github.com>

* Apply the rest of the suggestions from the code review

* Revert "Apply the rest of the suggestions from the code review"

This reverts commit 498be1b7a1aec3ff567b95130148628beeef9b77.

* Revert "Merge branch 'rewrite-and-refactor-all-documentation' of github.com:David-Else/helix into rewrite-and-refactor-all-documentation"

This reverts commit 7c8404248ffef73b80b9051d5a4359c5bcfa5d1a, reversing
changes made to d932969cfc9fadda12a74cc01665919dee7152fb.

* Apply code review suggestions

* Changes after re-reading all documents

* Missed a full stop

* Code review suggestions and remove macOS and Windows specific sections

* Add OpenBSD to heading

* Add back macOS and Windows sections and further simplify and improve

* Change wording to nightly

* Remove README installation section and turn into a link

* Simplify building from source and follow code review suggestions

* Code review revisions

* Fix copy paste mistake

* Apply the latest code review suggestions

* More small code review items

* Change minor modes for code review

* Fix link and typos

* Add note that you need a c++ compiler to install the tree-sitter grammars

* Add pacman example

* Make sure all headings are lower case

* Revert to the original passage adding a reference to Windows that was missing

* Update book/src/guides/adding_languages.md

Fix grammar typo

Co-authored-by: Michael Davis <mcarsondavis@gmail.com>

* Update book/src/install.md

Fix tree sitter typo

Co-authored-by: Michael Davis <mcarsondavis@gmail.com>

* Remove TOC links to main heading

---------

Co-authored-by: CptPotato <3957610+CptPotato@users.noreply.github.com>
Co-authored-by: Michael Davis <mcarsondavis@gmail.com>
Co-authored-by: digidoor <37601466+digidoor@users.noreply.github.com>

1 files changed, 53 insertions, 45 deletions

diff --git a/book/src/themes.md b/book/src/themes.md
index 9b7e97a1..af238e94 100644
--- a/book/src/themes.md
+++ b/book/src/themes.md
@@ -1,14 +1,15 @@
 # Themes
 
-To use a theme add `theme = "<name>"` to your [`config.toml`](./configuration.md) at the very top of the file before the first section or select it during runtime using `:theme <name>`.
+To use a theme add `theme = "<name>"` to the top of your [`config.toml`](./configuration.md) file, or select it during runtime using `:theme <name>`.
 
 ## Creating a theme
 
-Create a file with the name of your theme as file name (i.e `mytheme.toml`) and place it in your `themes` directory (i.e `~/.config/helix/themes`). The directory might have to be created beforehand.
+Create a file with the name of your theme as the file name (i.e `mytheme.toml`) and place it in your `themes` directory (i.e `~/.config/helix/themes` or `%AppData%\helix\themes` on Windows). The directory might have to be created beforehand.
 
-The names "default" and "base16_default" are reserved for the builtin themes and cannot be overridden by user defined themes.
+> 💡 The names "default" and "base16_default" are reserved for built-in themes
+> and cannot be overridden by user-defined themes.
 
-The default theme.toml can be found [here](https://github.com/helix-editor/helix/blob/master/theme.toml), and user submitted themes [here](https://github.com/helix-editor/helix/blob/master/runtime/themes). 
+### Overview
 
 Each line in the theme file is specified as below:
 
@@ -16,7 +17,7 @@ Each line in the theme file is specified as below:
 key = { fg = "#ffffff", bg = "#000000", underline = { color = "#ff0000", style = "curl"}, modifiers = ["bold", "italic"] }
 ```
 
-where `key` represents what you want to style, `fg` specifies the foreground color, `bg` the background color, `underline` the underline `style`/`color`, and `modifiers` is a list of style modifiers. `bg`, `underline` and `modifiers` can be omitted to defer to the defaults.
+Where `key` represents what you want to style, `fg` specifies the foreground color, `bg` the background color, `underline` the underline `style`/`color`, and `modifiers` is a list of style modifiers. `bg`, `underline` and `modifiers` can be omitted to defer to the defaults.
 
 To specify only the foreground color:
 
@@ -24,15 +25,30 @@ To specify only the foreground color:
 key = "#ffffff"
 ```
 
-if the key contains a dot `'.'`, it must be quoted to prevent it being parsed as a [dotted key](https://toml.io/en/v1.0.0#keys).
+If the key contains a dot `'.'`, it must be quoted to prevent it being parsed as a [dotted key](https://toml.io/en/v1.0.0#keys).
 
 ```toml
 "key.key" = "#ffffff"
 ```
 
+For inspiration, you can find the default `theme.toml`
+[here](https://github.com/helix-editor/helix/blob/master/theme.toml) and
+user-submitted themes
+[here](https://github.com/helix-editor/helix/blob/master/runtime/themes).
+
+### Using the linter
+
+Use the supplied linting tool to check for errors and missing scopes:
+
+```sh
+cargo xtask themelint onedark # replace onedark with <name>
+```
+
+## The details of theme creation
+
 ### Color palettes
 
-It's recommended define a palette of named colors, and refer to them from the
+It's recommended to define a palette of named colors, and refer to them in the
 configuration values in your theme. To do this, add a table called
 `palette` to your theme file:
 
@@ -45,8 +61,8 @@ white = "#ffffff"
 black = "#000000"
 ```
 
-Remember that the `[palette]` table includes all keys after its header,
-so you should define the palette after normal theme options.
+Keep in mind that the `[palette]` table includes all keys after its header,
+so it should be defined after the normal theme options.
 
 The default palette uses the terminal's default 16 colors, and the colors names
 are listed below. The `[palette]` section in the config file takes precedence
@@ -73,9 +89,8 @@ over it and is merged into the default palette.
 
 ### Modifiers
 
-The following values may be used as modifiers. 
-
-Less common modifiers might not be supported by your terminal emulator.
+The following values may be used as modifier, provided they are supported by
+your terminal emulator.
 
 | Modifier             |
 | ---                  |
@@ -89,14 +104,13 @@ Less common modifiers might not be supported by your terminal emulator.
 | `hidden`             |
 | `crossed_out`        |
 
-> Note: The `underlined` modifier is deprecated and only available for backwards compatibility.
+> 💡 The `underlined` modifier is deprecated and only available for backwards compatibility.
 > Its behavior is equivalent to setting `underline.style="line"`.
 
-### Underline Style
-
-One of the following values may be used as a value for `underline.style`. 
+### Underline style
 
-Some styles might not be supported by your terminal emulator.
+One of the following values may be used as a value for `underline.style`, providing it is
+supported by your terminal emulator.
 
 | Modifier       |
 | ---            |
@@ -109,7 +123,7 @@ Some styles might not be supported by your terminal emulator.
 
 ### Inheritance
 
-Extend upon other themes by setting the `inherits` property to an existing theme.
+Extend other themes by setting the `inherits` property to an existing theme.
 
 ```toml
 inherits = "boo_berry"
@@ -124,19 +138,19 @@ berry = "#2A2A4D"
 
 ### Scopes
 
-The following is a list of scopes available to use for styling.
+The following is a list of scopes available to use for styling:
 
 #### Syntax highlighting
 
 These keys match [tree-sitter scopes](https://tree-sitter.github.io/tree-sitter/syntax-highlighting#theme).
 
-For a given highlight produced, styling will be determined based on the longest matching theme key. For example, the highlight `function.builtin.static` would match the key `function.builtin` rather than `function`.
+When determining styling for a highlight, the longest matching theme key will be used. For example, if the highlight is `function.builtin.static`, the key `function.builtin` will be used instead of `function`.
 
 We use a similar set of scopes as
-[SublimeText](https://www.sublimetext.com/docs/scope_naming.html). See also
+[Sublime Text](https://www.sublimetext.com/docs/scope_naming.html). See also
 [TextMate](https://macromates.com/manual/en/language_grammars) scopes.
 
-- `attribute` - Class attributes, html tag attributes
+- `attribute` - Class attributes, HTML tag attributes
 
 - `type` - Types
   - `builtin` - Primitive types provided by the language (`int`, `usize`)
@@ -144,7 +158,7 @@ We use a similar set of scopes as
     - `variant`
 - `constructor`
 
-- `constant` (TODO: constant.other.placeholder for %v)
+- `constant` (TODO: constant.other.placeholder for `%v`)
   - `builtin` Special constants provided by the language (`true`, `false`, `nil` etc)
     - `boolean`
   - `character`
@@ -162,11 +176,11 @@ We use a similar set of scopes as
 
 - `comment` - Code comments
   - `line` - Single line comments (`//`)
-  - `block` - Block comments (e.g. (`/*     */`)
+  - `block` - Block comments (e.g. (`/* */`)
     - `documentation` - Documentation comments (e.g. `///` in Rust)
 
 - `variable` - Variables
-  - `builtin` - Reserved language variables (`self`, `this`, `super`, etc)
+  - `builtin` - Reserved language variables (`self`, `this`, `super`, etc.)
   - `parameter` - Function parameters
   - `other`
     - `member` - Fields of composite data types (e.g. structs, unions)
@@ -186,10 +200,10 @@ We use a similar set of scopes as
     - `return`
     - `exception`
   - `operator` - `or`, `in`
-  - `directive` - Preprocessor directives (`#if` in C) 
+  - `directive` - Preprocessor directives (`#if` in C)
   - `function` - `fn`, `func`
   - `storage` - Keywords describing how things are stored
-    - `type` - The type of something, `class`, `function`, `var`, `let`, etc. 
+    - `type` - The type of something, `class`, `function`, `var`, `let`, etc.
     - `modifier` - Storage modifiers like `static`, `mut`, `const`, `ref`, etc.
 
 - `operator` - `||`, `+=`, `>`
@@ -216,9 +230,9 @@ We use a similar set of scopes as
   - `bold`
   - `italic`
   - `link`
-    - `url` - urls pointed to by links
-    - `label` - non-url link references
-    - `text` - url and image descriptions in links
+    - `url` - URLs pointed to by links
+    - `label` - non-URL link references
+    - `text` - URL and image descriptions in links
   - `quote`
   - `raw`
     - `inline`
@@ -232,19 +246,19 @@ We use a similar set of scopes as
 
 #### Interface
 
-These scopes are used for theming the editor interface.
+These scopes are used for theming the editor interface:
 
 - `markup`
   - `normal`
-    - `completion` - for completion doc popup ui
-    - `hover` - for hover popup ui
+    - `completion` - for completion doc popup UI
+    - `hover` - for hover popup UI
   - `heading`
-    - `completion` - for completion doc popup ui
-    - `hover` - for hover popup ui
+    - `completion` - for completion doc popup UI
+    - `hover` - for hover popup UI
   - `raw`
     - `inline`
-      - `completion` - for completion doc popup ui
-      - `hover` - for hover popup ui
+      - `completion` - for completion doc popup UI
+      - `hover` - for hover popup UI
 
 
 | Key                         | Notes                                                                                          |
@@ -270,9 +284,9 @@ These scopes are used for theming the editor interface.
 | `ui.statusline.insert`      | Statusline mode during insert mode ([only if `editor.color-modes` is enabled][editor-section]) |
 | `ui.statusline.select`      | Statusline mode during select mode ([only if `editor.color-modes` is enabled][editor-section]) |
 | `ui.statusline.separator`   | Separator character in statusline                                                              |
-| `ui.popup`                  | Documentation popups (e.g Space + k)                                                           |
+| `ui.popup`                  | Documentation popups (e.g. Space + k)                                                          |
 | `ui.popup.info`             | Prompt for multiple key options                                                                |
-| `ui.window`                 | Border lines separating splits                                                                 |
+| `ui.window`                 | Borderlines separating splits                                                                  |
 | `ui.help`                   | Description box for commands                                                                   |
 | `ui.text`                   | Command prompts, popup text, etc.                                                              |
 | `ui.text.focus`             |                                                                                                |
@@ -301,10 +315,4 @@ These scopes are used for theming the editor interface.
 | `diagnostic.warning`        | Diagnostics warning (editing area)                                                             |
 | `diagnostic.error`          | Diagnostics error (editing area)                                                               |
 
-You can check compliance to spec with
-
-```shell
-cargo xtask themelint onedark  # replace onedark with <name>
-```
-
 [editor-section]: ./configuration.md#editor-section