X-Git-Url: https://arthur.barton.de/gitweb/?p=ax-zsh.git;a=blobdiff_plain;f=README.md;h=3ddbd0cb9287f4bae4d42f278a3b7e5943c8a11c;hp=6e3c05ac62347bbfa944bfdb7e04f55fe49a6109;hb=fe022068b9a1f957db3c1845f225494bbe09132b;hpb=9b2a55c02bd475f988bee63ea339484015ff52f2

diff --git a/README.md b/README.md
index 6e3c05a..3ddbd0c 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,69 @@
 AX-ZSH: Alex' Modular ZSH Configuration
 =======================================
 
+AX-ZSH is a modular configuration system for the Z shell (ZSH).
+It provides sane defaults and is extendable by plugins.
+
+Installation
+------------
+
+To install AX-ZSH, either download a source archive or use Git to clone it.
+Afterwards use the `install.sh` script inside of the source directory to set
+up the `~/.axzsh` directory.
+
+When using Git it is best to directly clone the AX-ZSH repository into the
+`~/.axzsh` directory and call `install.sh` from this location.
+
+Clone repository from _GitHub_ (<https://github.com/alexbarton/ax-zsh>):
+
+    git clone https://github.com/alexbarton/ax-zsh.git ~/.axzsh
+
+Then run the installer script:
+
+    ~/.axzsh/install.sh
+
+The `install.sh` script creates symbolic links for `~/.zprofile`, `~/.zshrc`,
+`~/.zlogin`, and `~/.zlogout` (don't worry, already existing files are backed
+up).
+
+Now close and restart all your running ZSH session to activate AX-ZSH.
+
+To update AX-ZSH run `axzshctl upgrade`.
+
+AX-ZSH & Local ZSH Configuration
+--------------------------------
+
+Plugins are loaded when they are linked into the `$AXZSH/active_plugins/`
+directory; see the _Customization_ section below for how to activate them.
+
+Don't modify `~/.zprofile`, `~/.zshrc`, `~/.zlogin`, or `~/.zlogout`! These
+are links to "AX-ZSH"-private files that can become overwritten when updating.
+
+You can use the following files for local ZSH configuration:
+
+1. AX-ZSH doesn't use `~/.zshenv` in any way. So you can use this file for your
+   own purposes (for example, to set up some environment variables that AX-ZSH
+   relies on).
+
+2. AX-ZSH reads the optional files `~/.zprofile.local`, `~/.zshrc.local`,
+   `~/.zlogin.local`, and `~/.zlogout.local` after its own core initialization
+   files when present.
+
+Customization
+-------------
+
+Use the `axzshctl` tool to enable, disable, and reset plugins. AXZSH
+initializes an alias which points to the actual location in `~/.axzsh/bin/`.
+
+See `axzshctl --help` for details.
+
+You can link custom plugins stored in arbitrary directories using `axzshctl`
+by specifying the complete path name. Or you can place additional plugins into
+the `~/.axzsh/custom_plugins` folder which is searched by the `axzshctl` tool
+by default.
+
+In addition you can set the `AXZSH_PLUGIN_D` variable (and `ZSH_CUSTOM` like
+"OhMyZsh") to specify additional plugin search directories.
 
 Environment Variables
 ---------------------
@@ -19,50 +82,6 @@ Validated and/or set up by core plugins:
 * `PS1`
 * `SHORT_HOST`
 * `TERM`
+* `XDG_RUNTIME_DIR`
 * `XDG_CACHE_HOME`
 * `ZSH_CACHE_DIR`
-
-
-Configuration
--------------
-
-AX-ZSH can be configured using settings in a `$HOME/.zshenv` file.
-
-The following configuration variables are supported:
-
-* `AXZSH_PLUGIN_D`: Optional directory for additional plugins.
-* `axzsh_default_plugins`: Array of default plugins, that will be loaded in
-  addition to the core plugins. You can reset this array to disable(!) loading
-  of these default plugins. Currently these plugins are loaded by default:
-   * byebye
-   * completion
-   * correction
-   * history
-   * ls
-   * prompt
-   * ssh
-   * std_aliases
-   * std_env
-* `axzsh_plugins`: Optional array of addiutional (non-core and non-default)
-  plugins to load.
-
-Example for a `$HOME/.zshenv` file:
-
-```
-# Add additinal custom plugin search path
-export AXZSH_PLUGIN_D="/opt/ax-zsh-plugins"
-
-# Disable all default plugins
-typedef -U axzsh_default_plugins
-axzsh_default_plugins=()
-
-# Add additional plugins
-typedef -U axzsh_plugins
-axzsh_plugins=(
-	editor_select
-	homebrew
-)
-```
-
-Note: it should *not* be necessary to disable the default plugins! The above
-is an example only!