fix(manual): section general rules and REPL instead of misc + rewordings

manual/src/SUMMARY.md

@@ -4,16 +4,9 @@
 
 - [Migrating from POSIX shells](migrating.md)
 
-- [Miscellaneous](misc/index.md)
-
-    - [Implicit `cd`](misc/01-implicitcd.md)
-    - [XDG App Directories](misc/02-xdg.md)
-    - [Quoting Rules](misc/03-quotation.md)
-    - [Multi-line Arguments](misc/04-multiargs.md)
-    - [Multi-line Strings](misc/05-multiline-strings.md)
-    - [Prompt Function](misc/06-prompt_fn.md)
-    - [Key Bindings](misc/07-keybindings.md)
-    - [General Tips](misc/08-general.md)
+- [General rules](general.md)
+
+- [Read–eval–print loop](repl.md)
 
 - [Variables](variables/00-variables.md)
 

manual/src/misc/02-xdg.md → manual/src/general.md

-# XDG App Dirs Support
+# General rules
 
-All files created by Ion can be found in their respective XDG application directories. In example,
+## Performance: Let Arithmetic vs Arithmetic Expansions
+**let** arithmetic is generally faster than **$(())** expansions. The arithmetic expansions
+should be used for increasing readability, or more complex arithmetic. If speed is important:
+Multiple *let arithmetic statements will tend to be faster* than a single arithmetic expansion.
+
+## Quoting Rules
+- Variables are expanded in double quotes, but not single quotes.
+- Braces are expanded when unquoted, but not when quoted.
+
+## XDG App Dirs Support
+All files created by Ion can be found in their respective XDG application directories. For example,
 the init file for Ion can be found in **$HOME/.config/ion/initrc** on Linux systems; and the
 history file can be found at **$HOME/.local/share/ion/history**. On the first launch of Ion, a
 message will be given to indicate the location of these files.

manual/src/introduction.md

@@ -9,15 +9,18 @@ platforms, and we are currently searching for a Windows developer to port it to
 
 # Goals
 
-Syntax and feature decisions for Ion are made based upon three measurements: is the feature useful,
-is it simple to use, and will it's implementation be efficient to parse and execute? A feature is
-considered useful if there's a valid use case for it, in the concept of a shell language. The
+Syntax and feature decisions for Ion are made based upon three measurements: 
+ 1. Is the feature useful?
+ 2. Is it simple to use?
+ 3. Will it's implementation be efficient to parse and execute? 
+
+A feature is considered useful if there's a valid use case for it, in the concept of a shell language. The
 syntax for the feature should be simple for a human to read and write, with extra emphasis on
-readability, given that most time is spent reading scripts than writing them. The implementation
-should require minimal to zero heap allocations, and be implemented in a manner that requires
-minimal CPU cycles (so long as it's also fully documented and easy to maintain!).
+readability, given that **most time is spent reading scripts** than writing them. The implementation
+should require *minimal to zero heap allocations*, and be implemented in a manner that requires
+*minimal CPU cycles* (so long as it's also **fully documented** and **easy to maintain**!).
 
-It should also be taken into consideration that shells operate entirely upon strings, and therefore
+It should also be taken into consideration that *shells operate entirely upon strings*, and therefore
 should be fully equipped for all manner of string manipulation capabilities. That means that users
 of a shell should not immediately need to grasp for tools like **cut**, **sed**, and **awk**. Ion
 offers a great deal of control over slicing and manipulating text. Arrays are treated as first

manual/src/misc/01-implicitcd.md

-# Implicit `cd`
-
-Like the [Friendly Interactive Shell](https://fishshell.com/), Ion also supports
-executing the `cd` command automatically
-when given a path. Paths are denoted by beginning with `.`/`/`/`~`, or ending with `/`.
-
-```sh
-~/Documents # cd ~/Documents
-..          # cd ..
-.config     # cd .config
-examples/   # cd examples/
-```

manual/src/misc/03-quotation.md

-# Quoting Rules
-
-- Variables are expanded in double quotes, but not single quotes.
-- Braces are expanded when unquoted, but not when quoted.

manual/src/misc/04-multiargs.md

-# Multi-line Arguments
-
-If a line in your script becomes too long, you may signal to Ion to continue reading the next line
-by appending an `\` character at the end of the line. This will ignore newlines.
-
-```sh
-command arg arg2 \
-    arg3 arg4 \
-    arg 5
-```

manual/src/misc/05-multiline-strings.md

-# Multi-line Strings
-
-If a string needs to contain newlines, you may do so by having an open quote, as Ion will only
-begin parsing supplied commands that are terminated. Either double or single quotes may be used
-for this purpose, depending on which quoting rules that you need.
-
-```sh
-echo "This is the first line
-    this is the second line
-    this is the third line"
-```

manual/src/misc/06-prompt_fn.md

-# Prompt Function
-
-The prompt may optionally be generated from a function, instead of a string. Take note, however,
-that prompts generated from functions aren't as efficient, due to the need to perform a fork and
-capture the output of the fork to use as the prompt. To use a function for generating the prompt,
-simply create a function whose name is **PROMPT**, and the output of that command will be used as
-the prompt. Below is an example:
-
-```
-fn PROMPT
-    echo -n "${PWD}# "
-end
-```

manual/src/misc/07-keybindings.md

-# Key Bindings
-
-There are two pre-set key maps available: Emacs (default) and Vi.
-You can switch between them with the `keybindings` built-in command.
-
-```
-keybindings vi
-keybindings emacs
-```
-
-## Vi Mode Prompt Indicators
-
-In the Vi mode, you can define the displayed indicator for normal and insert modes
-with the following variables:
-
-```
-$ export VI_NORMAL = "[=] "
-$ export VI_INSERT = "[+] "
-$ keybindings vi
-[+] $
-```

manual/src/misc/08-general.md

-# General Tips
-
-## Let Arithmetic vs Arithmetic Expansions
-
-Using **let** arithmetic is generally faster than **$(())** expansions. The arithmetic expansions
-should be used for increasing readability, or more complex arithmetic; but if speed is important,
-multiple let arithmetic statements will tend to be faster than a single arithmetic expansion.

manual/src/misc/index.md

-# Miscellaneous

manual/src/repl.md

+# Read-eval-print loop
+
+## Implicit `cd`
+Like the [Friendly Interactive Shell](https://fishshell.com/), Ion also supports
+executing the `cd` command automatically
+when given a path. Paths are denoted by beginning with `.`/`/`/`~`, or ending with `/`.
+```sh
+~/Documents # cd ~/Documents
+..          # cd ..
+.config     # cd .config
+examples/   # cd examples/
+```
+
+## Multi-line Arguments
+If a line in your script becomes too long, appending `\` will make Ion ignore newlines
+and continue reading the next line.
+```sh
+command arg arg2 \
+    arg3 arg4 \
+    arg 5
+```
+
+## Multi-line Strings
+If a string needs to contain newlines, you use an open quote. Ion will only
+begin parsing supplied commands that are terminated. Either double or single quotes can be used.
+```sh
+echo "This is the first line
+    this is the second line
+    this is the third line"
+```
+
+## Prompt Function
+The prompt may optionally be generated from a function, instead of a string. Due to the need to
+perform a fork an capture of its output as prompt, prompts generated from functions aren't as
+efficient. Below the requirement to use the function with name **PROMPT**:
+```sh
+fn PROMPT
+    echo -n "${PWD}# "
+end
+```
+
+## Key Bindings
+There are two pre-set key maps available: **Emacs (default)** and **Vi**.
+You can switch between them with the `keybindings` built-in command.
+```sh
+keybindings vi
+keybindings emacs
+```
+**Vi keybinding**: You can define the displayed indicator for normal and insert modes
+with the following variables:
+```sh
+$ export VI_NORMAL = "[=] "
+$ export VI_INSERT = "[+] "
+$ keybindings vi
+[+] $
+```