general: Update documentation better qualifying runcom paths

Zsh and Prezto files don't always reside in `~/`. Instead, they have
a more spec compliant location (`${ZDOTDIR:-$HOME}/`). Make them
unambiguous in the documentation. Likewise, for `$GNUPGHOME`.

Further, add instruction for optionally setting up Prezto in
`$XDG_CONFIG_HOME`.

While at this, also add clarification on relative ordering of some of
the modules, apply more formatting tweaks and doc improvements.

README.md

@@ -21,8 +21,32 @@ version is **4.3.11**.
     git clone --recursive https://github.com/sorin-ionescu/prezto.git "${ZDOTDIR:-$HOME}/.zprezto"
     ```
 
-03. Create a new Zsh configuration by copying the Zsh configuration files
-    provided:
+    <details>
+      <summary><em>Optional: Installing in <code>$XDG_CONFIG_HOME</code></em></summary>
+
+      Optionally, if you already have `$XDG_CONFIG_HOME` configured (usually as
+      _`$HOME/.config`_ by default) and intend to install Prezto under
+      _`$XDG_CONFIG_HOME/zsh`_ instead, you can clone the repository there and
+      configure `$ZDOTDIR` separately if not already configured.
+
+      - Clone the repository:
+
+        ```console
+        git clone --recursive https://github.com/sorin-ionescu/prezto.git "${ZDOTDIR:-${XDG_CONFIG_HOME:-$HOME/.config}/zsh}/.zprezto"
+        ```
+
+      - Configure `$XDG_CONFIG_HOME` and `$ZDOTDIR` in _`${$HOME}/.zshenv`_:
+
+        ```sh
+        export XDG_CONFIG_HOME="${XDG_CONFIG_HOME:=$HOME/.config}"
+        export ZDOTDIR="${ZDOTDIR:=$XDG_CONFIG_HOME/zsh}"
+        source "$ZDOTDIR/.zshenv"
+        ```
+
+    </details>
+
+03. Create a new Zsh configuration by copying/linking the Zsh configuration
+    files provided:
 
     ```console
     setopt EXTENDED_GLOB
@@ -34,10 +58,10 @@ version is **4.3.11**.
     **Note:** If you already have any of the given configuration files, `ln` in
     the above operation will cause an error. In simple cases, you can load
     Prezto by adding the line `source "${ZDOTDIR:-$HOME}/.zprezto/init.zsh"` to
-    the bottom of your *${ZDOTDIR:-$HOME}/.zshrc* and keep the rest of your Zsh
-    configuration intact. For more complicated setups, we recommend that you
+    the bottom of your _`${ZDOTDIR:-$HOME}/.zshrc`_ and keep the rest of your
+    Zsh configuration intact. For more complicated setups, we recommend that you
     back up your original configs and replace them with the provided Prezto
-    *runcoms*.
+    [_`runcoms`_][10].
 
 04. Set Zsh as your default shell:
 
@@ -50,7 +74,7 @@ version is **4.3.11**.
 ### Troubleshooting
 
 If you are not able to find certain commands after switching to Prezto, modify
-the `PATH` variable in *${ZDOTDIR:-$HOME}/.zprofile* then open a new Zsh
+the `PATH` variable in _`${ZDOTDIR:-$HOME}/.zprofile`_ then open a new Zsh
 terminal window or tab.
 
 ## Updating
@@ -76,33 +100,33 @@ accompanying README files to learn about what is available.
 
 ### Modules
 
-01. Browse */modules* to see what is available.
-02. Load the modules you need in *${ZDOTDIR:-$HOME}/.zpreztorc* then open a new
-    Zsh terminal window or tab.
+01. Browse [_`modules`_][9] to see what is available.
+02. Load the modules you need in _`${ZDOTDIR:-$HOME}/.zpreztorc`_ and then open
+    a new Zsh terminal window or tab.
 
 ### Themes
 
 01. For a list of themes, type `prompt -l`.
 02. To preview a theme, type `prompt -p name`.
-03. Load the theme you like in *${ZDOTDIR:-$HOME}/.zpreztorc* then open a new
-    Zsh terminal window or tab.
+03. Load the theme you like in _`${ZDOTDIR:-$HOME}/.zpreztorc`_ and then
+    open a new Zsh terminal window or tab.
 
     ![sorin theme][2]
-    Note that the *git* module may be required for special symbols to appear,
-    such as those on the right of the above image. Add `'git'` to the `pmodule`
-    list (under `zstyle ':prezto:load' pmodule \` in your
-    *${ZDOTDIR:-$HOME}/.zpreztorc*) to enable this module.
+    Note that the [_`git`_][11] module may be required for special symbols to
+    appear, such as those on the right of the above image. Add `'git'` to the
+    `pmodule` list (under `zstyle ':prezto:load' pmodule \` in your
+    _`${ZDOTDIR:-$HOME}/.zpreztorc`_) to enable this module.
 
 ### External Modules
 
-01. By default modules will be loaded from */modules* and */contrib*.
+01. By default modules will be loaded from [_`/modules`_][9] and _`/contrib`_.
 02. Additional module directories can be added to the
-    `:prezto:load:pmodule-dirs` setting in *${ZDOTDIR:-$HOME}/.zpreztorc*.
+    `:prezto:load:pmodule-dirs` setting in _`${ZDOTDIR:-$HOME}/.zpreztorc`_.
 
     Note that module names need to be unique or they will cause an error when
     loading.
 
-    ```console
+    ```sh
     zstyle ':prezto:load' pmodule-dirs $HOME/.zprezto-contrib
     ```
 
@@ -129,3 +153,6 @@ This project is licensed under the MIT License.
 [6]: https://git.github.io/git-reference/
 [7]: http://www.bash2zsh.com/zsh_refcard/refcard.pdf
 [8]: https://grml.org/zsh/zsh-lovers.html
+[9]: modules#readme
+[10]: runcoms#readme
+[11]: modules/git#readme

modules/README.md

@@ -1,6 +1,6 @@
 # Modules
 
-Load modules in *~/.zpreztorc*. The order matters.
+Load modules in _`${ZDOTDIR:-$HOME}/.zpreztorc`_. The order matters.
 
 ```sh
 zstyle ':prezto:load' pmodule 'environment' 'terminal'
@@ -29,11 +29,11 @@ Sets directory options and defines directory aliases.
 
 ## DNF
 
-Defines *dnf* aliases.
+Defines _dnf_ aliases.
 
 ## Dpkg
 
-Defines *dpkg* aliases and functions.
+Defines _dpkg_ aliases and functions.
 
 ## Editor
 

modules/archive/README.md

@@ -2,6 +2,10 @@
 
 Provides functions to create, list, and extract archives.
 
+This module must be loaded _before_ the [_`completion`_][1] module so that the
+provided completion definitions are loaded automatically by _`completion`_
+module.
+
 ## Functions
 
 - `archive` creates an archive based on the provided archive name.
@@ -13,35 +17,37 @@ Provides functions to create, list, and extract archives.
 The following archive formats are supported when the required utilities are
 installed:
 
-- *.tar.gz*, *.tgz* require `tar` (optionally `pigz`).
-- *.tar.bz2*, *.tbz* require `tar` (optionally `pbzip2`).
-- *.tar.xz*, *.txz* require `tar` with *xz* support.
-- *.tar.zma*, *.tlz* require `tar` with *lzma* support.
-- *.tar* requires `tar`.
-- *.gz* requires `gunzip`.
-- *.bz2* requires `bunzip2`.
-- *.xz* requires `unxz`.
-- *.lzma* requires `unlzma`.
-- *.Z* requires `uncompress`.
-- *.zip*, *.jar* requires `unzip`.
-- *.rar* requires `rar` (needed for `archive` support), `unrar` or `lsar` and `unar`.
-- *.7z* requires `7za`.
-- *.deb* requires `ar`, `tar`.
+- _.tar.gz_, _.tgz_ require `tar` (optionally `pigz`).
+- _.tar.bz2_, _.tbz_ require `tar` (optionally `pbzip2`).
+- _.tar.xz_, _.txz_ require `tar` with _xz_ support.
+- _.tar.zma_, _.tlz_ require `tar` with _lzma_ support.
+- _.tar_ requires `tar`.
+- _.gz_ requires `gunzip`.
+- _.bz2_ requires `bunzip2`.
+- _.xz_ requires `unxz`.
+- _.lzma_ requires `unlzma`.
+- _.Z_ requires `uncompress`.
+- _.zip_, _.jar_ requires `unzip`.
+- _.rar_ requires `rar` (needed for `archive` support), `unrar` or `lsar` and `unar`.
+- _.7z_ requires `7za`.
+- _.deb_ requires `ar`, `tar`.
 
 Additionally, if `pigz` and/or `pbzip2` are installed, `archive` will use them
 over their traditional counterparts, `gzip` and `bzip2` respectively, to take
 full advantage of all available CPU cores for compression.
 
 ## Alternatives
 
-Specifically on macOS, [The Unarchiver][1] provides a similar command line tool
+Specifically on macOS, [The Unarchiver][2] provides a similar command line tool
 which doesn't depend on a number of other programs being installed.
 
 ## Authors
 
-*The authors of this module should be contacted via the [issue tracker][1].*
+_The authors of this module should be contacted via the [issue tracker][3]._
 
 - [Sorin Ionescu](https://github.com/sorin-ionescu)
 - [Matt Hamilton](https://github.com/Eriner)
 
-[1]: https://theunarchiver.com/command-line
+[1]: ../completion#readme
+[2]: https://theunarchiver.com/command-line
+[3]: https://github.com/sorin-ionescu/prezto/issues

modules/autosuggestions/README.md

@@ -5,13 +5,16 @@ Integrates [zsh-autosuggestions][1] into Prezto, which implements the
 of a previously entered command and Zsh suggests commands as you type based on
 history and completions.
 
-If this module is used in conjunction with the *syntax-highlighting* module,
-this module must be loaded **after** the *syntax-highlighting* module.
+If this module is used in conjunction with the [_`syntax-highlighting`_][3]
+module, this module must be loaded _after_ the _`syntax-highlighting`_ module.
 
-If this module is used in conjunction with the *history-substring-search*
-module, this module must be loaded **after** the *history-substring-search*
+If this module is used in conjunction with the [_`history-substring-search`_][4]
+module, this module must be loaded _after_ the _`history-substring-search`_
 module.
 
+To elaborate, the relative order of loading the modules would be
+_`autosuggestions`_, _`syntax-highlighting`_ and _`history-substring-search`_.
+
 ## Contributors
 
 New features and bug fixes should be submitted to the [zsh-autosuggestions][1]
@@ -22,17 +25,18 @@ against it.
 
 ### Highlighting
 
-If colors are enabled, *autosuggestions* will automatically highlight
+If colors are enabled, _autosuggestions_ will automatically highlight
 positive results.
 
 To enable highlighting for this module only, add the following line to
-*~/.zpreztorc*:
+_`${ZDOTDIR:-$HOME}/.zpreztorc`_:
 
 ```sh
 zstyle ':prezto:module:autosuggestions' color 'yes'
 ```
 
-To set the query found color, add the following line to *~/.zpreztorc*:
+To set the query found color, add the following line to
+_`${ZDOTDIR:-$HOME}/.zpreztorc`_:
 
 ```sh
 zstyle ':prezto:module:autosuggestions:color' found ''
@@ -47,10 +51,12 @@ also have the `history` module enabled.
 
 ## Authors
 
-*The authors of this module should be contacted via the [issue tracker][3].*
+_The authors of this module should be contacted via the [issue tracker][5]._
 
 - [Sorin Ionescu](https://github.com/sorin-ionescu)
 
 [1]: https://github.com/tarruda/zsh-autosuggestions
 [2]: https://fishshell.com
-[3]: https://github.com/sorin-ionescu/prezto/issues
+[3]: ../syntax-highlighting#readme
+[4]: ../history-substring-search#readme
+[5]: https://github.com/sorin-ionescu/prezto/issues

modules/command-not-found/README.md

@@ -12,7 +12,7 @@ a recent version of Homebrew installed, you might also need to tap the
 
 ## Authors
 
-*The authors of this module should be contacted via the [issue tracker][4].*
+_The authors of this module should be contacted via the [issue tracker][4]._
 
 - [Joseph Booker](https://github.com/sargas)
 - [Indrajit Raychaudhuri](https://github.com/indrajitr)

modules/completion/README.md

@@ -3,7 +3,8 @@
 Loads and configures <kbd>TAB</kbd> completion and provides additional
 completions from the [zsh-completions][1] project.
 
-This module must be loaded **after** the *utility* module.
+This module must be loaded late _after_ the _`utility`_ module and all other
+modules that provide completion definitions.
 
 ## Options
 
@@ -14,24 +15,24 @@ This module must be loaded **after** the *utility* module.
 - `AUTO_LIST` automatically list choices on ambiguous completion.
 - `AUTO_PARAM_SLASH` if completed parameter is a directory, add a trailing
   slash (`/`).
-- `EXTENDED_GLOB` needed for file modification glob modifiers with *compinit*.
+- `EXTENDED_GLOB` needed for file modification glob modifiers with _compinit_.
 - `MENU_COMPLETE` do not autoselect the first completion entry.
 - `FLOW_CONTROL` disable start/stop characters in shell editor.
 
 ## Settings
 
-### Ignore */etc/hosts* Entries
+### Ignore _`/etc/hosts`_ Entries
 
-To ignore certain entries from static */etc/hosts* for host completion, add the
-following lines in *~/.zpreztorc* with the IP addresses of the hosts as they
-appear in */etc/hosts*. Both IP address and the corresponding hostname will be
-ignored during host completion. However, some of the entries ignored from
-*/etc/hosts* still might appear during completion because of their presence in
-*ssh* configuration or history).
+To ignore certain entries from static _`/etc/hosts`_ for host completion, add
+the following lines in _`${ZDOTDIR:-$HOME}/.zpreztorc`_ with the IP addresses of
+the hosts as they appear in _`/etc/hosts`_. Both IP address and the associated
+hostname(s) will be ignored during host completion. However, some of the entries
+ignored from _`/etc/hosts`_ still might appear during completion because of
+their presence in _ssh_ configuration or history).
 
 ```sh
 zstyle ':prezto:module:completion:*:hosts' etc-host-ignores \
-  '0.0.0.0' '127.0.0.1'
+    '0.0.0.0' '127.0.0.1'
 ```
 
 ## Contributors
@@ -41,7 +42,7 @@ its rules and regulations. This module will be synchronized against it.
 
 ## Authors
 
-*The authors of this module should be contacted via the [issue tracker][2].*
+_The authors of this module should be contacted via the [issue tracker][2]._
 
 - [Sorin Ionescu](https://github.com/sorin-ionescu)
 

modules/directory/README.md

@@ -22,7 +22,7 @@ Sets directory options and defines directory aliases.
 
 ## Authors
 
-*The authors of this module should be contacted via the [issue tracker][1].*
+_The authors of this module should be contacted via the [issue tracker][1]._
 
 - [James Cox](https://github.com/imajes)
 - [Sorin Ionescu](https://github.com/sorin-ionescu)

modules/dnf/README.md

@@ -17,7 +17,7 @@ Defines [dnf][1] aliases.
 
 ## Authors
 
-*The authors of this module should be contacted via the [issue tracker][2].*
+_The authors of this module should be contacted via the [issue tracker][2]._
 
 - [Sorin Ionescu](https://github.com/sorin-ionescu)
 

modules/docker/README.md

@@ -134,8 +134,10 @@ Defines [Docker][1] aliases and functions.
 - `dkm` is short for `docker-machine`
 - `dkma` Get or set the active machine
 - `dkmcp` Copy files between machines
-- `dkmd` Set up the default machine ; alowing you to use `dkme` without arguments
-- `dkme` Set up the environment for the Docker client (eg: `dkme staging` to toggle to staging)
+- `dkmd` Set up the default machine ; alowing you to use `dkme` without
+  arguments
+- `dkme` Set up the environment for the Docker client (eg: `dkme staging` to
+  toggle to staging)
 - `dkmin` Inspect information about a machine
 - `dkmip` Get the IP address of a machine
 - `dkmk` Kill a machine
@@ -175,8 +177,8 @@ Defines [Docker][1] aliases and functions.
 - `dkcsc` Set number of containers for a service
 - `dkcS` Restart services
 - `dkcu` Create and start containers
-- `dkcU` Create and start containers in detached mode:
-           Run containers in the background, print new container names
+- `dkcU` Create and start containers in detached mode: Run containers in the
+  background, print new container names
 - `dkcV` Show the Docker-Compose version information
 - `dkcx` Stop services
 

modules/dpkg/README.md

@@ -1,6 +1,6 @@
 # Dpkg
 
-Defines [*dpkg*][1] aliases and functions.
+Defines [_dpkg_][1] aliases and functions.
 
 ## Aliases
 
@@ -27,7 +27,7 @@ Defines [*dpkg*][1] aliases and functions.
 
 ## Authors
 
-*The authors of this module should be contacted via the [issue tracker][2].*
+_The authors of this module should be contacted via the [issue tracker][2]._
 
 - [Daniel Bolton](https://github.com/dbb)
 - [Benjamin Boudreau](https://github.com/dreur)