docs(Readme): Update Readme

Complete rewrite of Readme for hopefully better clarity.
Now covering all major features and differences

Readme.md

@@ -1,34 +1,194 @@
-# My ZSH config.
+# My ZSH configuration
 
-This is my personal ZSH config that I run on my laptop.
+This repository has a fully loaded configuration for ZSH.
-It works for what I want from a configured shell.
+The configuration make opinionated choices based on my own desires for what
+a shell should be like.
 
-I would recommend you actually create your own config before just using
+It's strongly advised that you write your own configuration instead of
-mine since you will gain a proper understanding of how ZSH works and just
+just using this one. That way you can understand what you are doing and
-what it can do.
+maybe gain a better appreciation for the shell and its features.
 
-I have attempted to organise my config into a series of files that each
+The configuration is broken down into modules where possible, this
-perform a specific task, that way it is easier for me to change small
+makes it easier to hack on.
-sections as the need arises.
 
-## How to use
+## Usage
 
-If you really really want to just blindly copy me then you will need to
+Clone this repository to `~/.config/zsh`
-clone this repository to `~/.config/zsh`
 
-Inside of the cloned repository run:
+Inside of that directory run:
 ```sh
 git submodule init
 git submodule update
 ```
-This will pull in the latest version of my plugin manager.
+This will pull my plug-in manager `ZshPlug`.
 
-And then add the following into your `~/.profile`:  
+And then add the following into `~/.zshenv`:
 ```sh
 export ZDOTDIR="${XDG_CONFIG_HOME:-$HOME/.config}/zsh"
 ```
+This tells ZSH where the ZSH dotfiles are.
 
-After your next reboot you _should_ be using my config.
+### Important note
+It is possible that your system might not be happy with this.
+I have yet to fully work out the little issues that I have with making a
+consistent environment across *all* of my user session.
 
-If anything goes wrong feel free to open an issue. But this is entirely a
+This might result in a need to create a system of linked environment files
-personal project for my own use, so don't expect anything.
+to ensure that everything can access the environment variables that are
+meant to be set.
+
+## Issues
+This is a personal project and is unlikely to be maintained in a
+professional manner.
+If you do find any technical issues during your usage of this config then
+feel free to open a GitHub issue.
+Please remember that GitHub issues are not a forum nor a place for you to
+ask questions not related to *technical issues*, and it is completely up to
+my own discretion what issues I handle and which ones I close.
+
+## General overview
+The main goals for this configuration are look good, work good, and be
+quick.
+The less things getting in my way the better.
+
+This is why I have made opinionated decisions about what options to enable
+and how it works.
+
+### Notable features
+
+ - Edit the command line in $EDITOR by pressing `C-x C-e`
+ - Fully configured completion
+ - Automatic typo repair
+ - vi mode enabled
+ - Automatic use of the directory stack `popd` to go back whence you came
+ - Smart history
+ - Plug-ins chosen for greatness
+
+## Breakdown
+The following sections break down what is in the repository and what
+function it does.
+
+### Modules
+
+#### `./aliases`
+This module features aliases that I find useful or ones that improve
+existing tools.
+Any alias that uses external tools uses the `has` function to disable it
+when the tool isn't installed.
+
+##### Current aliases:
+ - `ls` => `exa --icons --group-directories-first` (see: [Exa Website](https://the.exa.website/) )
+ - `xopen` => `xdg-open`
+ - `cls` => `clear; ls`
+ - `se` => `scriptedit` (wrapper script for fzf and nvim)
+ - `yt` => `youtube-dl`
+ - `yta` => `youtube-dl --ignore-config --add-metadata --ignore-errors --extract-audio --format "bestaudio/best"`
+ - `cp` => `cp --interactive --verbose`
+ - `mv` => `mv --interactive --verbose`
+ - `rm` => `rm --interactive=once --verbose`
+ - `mkd` => `mkdir --parents --verbose`
+ - `diff` => `diff --color=auto`
+ - `grep` => `grep --color=auto`
+ - `ip` => `ip --colour=auto`
+ - `vw` => `nvim -c VimwikiIndex`
+ - `ws` => `wineselect` (script to choose and set wine-prefix)
+ - `zero` => `dirs -c && clear`
+
+##### File associations
+This module is also responsible for in terminal file associations. Given a
+file with a particular extension ZSH can open it with the appropriate
+program.
+`tex`, `html`, and `md` files are mapped to either `nvim`, `vim`, or `vi`
+in that order of preference.
+`pdf` files are mapped to `zathura` when it's installed.
+
+#### `./chpwd`
+This module sets the `chpwd` hook and makes ZSH display any (markdown
+formatted) readme files
+found in the current directory using glow.
+
+#### `./completion`
+This file configures the powerful completion engine of
+ZSH.
+Documenting this here would be a waste since the file has decent comments.
+For more information on ZSH completion see `man zshcompsys`
+
+#### `./dir_aliases`
+This file uses `hash` to add entries into the named directory hash table.
+(See: `man zshbuiltins`)
+This gives the effect of these "aliases" that represent directories.
+- `~dx` => `$HOME/Documents`
+- `~dl` => `$HOME/Downloads`
+- `~cn` => `${XDG_CONFIG_HOME:-$HOME/.config}`
+- `~px` => `$HOME/Pictures`
+- `~pr` => `$HOME/Projects`
+
+#### `./greet`
+This file gets executed at the end of `zshrc` to provide a little message
+on startup.
+
+#### `./history`
+This file configures the ZSH history system.
+
+This makes a few changes:
+ - Moves history to `${XDG_STATE_HOME/zsh/history}`
+ - Ignores duplicate entries
+ - Ignore entries starting with a space
+ - Compacts whitespace
+ - Never saves duplicates
+ - Ignores duplicates when searching history
+ - Requires you press enter after expanding `!!`
+
+#### `./keyboard`
+This file uses `zkbd`(see `man zshcontrib`) to get information about your
+keyboard and how your terminal handles it. This can fix issues with keys
+not being recognised in programs.
+
+#### `./prompt`
+This file configures the prompts, and yes there's two.
+ZSH has both a left and right prompt and I use both of them.
+
+##### Left prompt
+The left prompt shows user, hostname, current directory, and the status of
+the last command.
+
+##### Right prompt
+The right prompt shows the status of git repository information while
+you're in one.
+
+##### `precmd`
+This file also sets the `precmd` hook to set the terminal title (for
+terminals which support the escape codes that do this.)
+
+#### `zshrc`
+This is the true `zshrc` file with `.zshrc` a symbolic link to this
+file.
+This makes it a little easier to edit the file since you can actually see
+it in `ls` and in editors.
+
+This file draws together the modules and actually makes
+settings apply.
+
+### Functions
+This configuration defines and loads some functions,
+some of which are helper functions used in the configuration.
+
+#### `CleanTmp`
+Function called during exit to clean a local tmp directory (`~/tmp`).
+
+#### `has`
+Just a wrapper for calling `command -v $COMMAND`.
+This function gets used to check for external tools.
+
+#### `setTermTitle`
+This function gets used in the prompt to set the terminal title.
+It makes use of escape sequences to control the terminal and might have
+issues on rare or unusual terminals.
+
+#### `tempPersist`
+This function controls if the local tmp directory (`~/tmp`) will persist across sessions or
+not.
+
+#### `_dotnet`
+This completion function that tells the completion engine how to
+complete `dotnet` commands.