[zsh] update documentation of ZPLG

zsh/zplg.zsh

@@ -35,12 +35,17 @@ _ZPLG_SCRIPT_PATH="${(%):-%N}"
 
 # $ZPLG_HOME is a directory where all your plugins are downloaded, it also
 # might contain in the future some kind of state/lock/database files. It is
-# recommended to change it before `source`-ing this script for compatitability
+# recommended to change it before `source`-ing this script because you may end
-# with future versions.
+# up with a broken plugin directory.
 if [[ -z "$ZPLG_HOME" ]]; then
   ZPLG_HOME="${XDG_DATA_HOME:-$HOME/.local/share}/zplg"
 fi
 
+# Default plugin source, see the `plugin` function for description.
+if [[ -z "$ZPLG_DEFAULT_SOURCE" ]]; then
+  ZPLG_DEFAULT_SOURCE="github"
+fi
+
 # Directory in which plugins are stored. It is separate from $ZPLG_HOME for
 # compatitability with future versions.
 _ZPLG_PLUGINS_DIR="$ZPLG_HOME/plugins"
@@ -117,7 +122,8 @@ _zplg_expand_pattern() {
   local pattern="$1" out_var_name="$2"
   # ${~var_name} turns on globbing for this expansion, note lack of quotes: as
   # it turns out glob expansions are automatically quoted by design, and when
-  # you explicitly write "${~pattern}" it is basically the same as "$pattern"
+  # you explicitly write `"${~pattern}"` it is basically the same as
+  # `"$pattern"`
   eval "$out_var_name=(\${~pattern})"
 }
 
@@ -189,7 +195,7 @@ _zplg_load() {
 #   function must, well, download a plugin from the given URL into the given
 #   directory, ugrade one, obviously, upgrades plugin inside of the given
 #   directory. Please note that neither of these functions is executed INSIDE
-#   of the plugin directory.
+#   of the plugin directory (i.e. current working directory is not changed).
 #
 # build (+)
 #   Command which builds/compiles the plugin, executed INSIDE of $plugin_dir
@@ -207,7 +213,7 @@ _zplg_load() {
 #
 # Neat trick when using options: if you want to assign values using an array,
 # write it like this: option=${^array}. That way `option=` is prepended to
-# each value of `array`.
+# each element of `array`.
 #
 # For examples see my dotfiles: https://github.com/dmitmel/dotfiles/blob/master/zsh/plugins.zsh
 # You may ask me why did I choose to merge loading and downloading behavior
@@ -251,7 +257,7 @@ plugin() {
 
   # parse options {{{
 
-    local plugin_from="github"
+    local plugin_from="$ZPLG_DEFAULT_SOURCE"
     local -a plugin_build plugin_before_load plugin_after_load plugin_load plugin_ignore
 
     local option key value; shift 2; for option in "$@"; do
@@ -386,20 +392,23 @@ _zplg_is_plugin_loaded() {
   (( ${ZPLG_LOADED_PLUGINS[(ie)$plugin_id]} <= ${#ZPLG_LOADED_PLUGINS} ))
 }
 
-# Here are some useful commands for managing plugins. I chose to make them
+# Useful commands for managing plugins {{{
-# functions because:
-# 1. automatic completion
-# 2. automatic correction
 
-# Prints IDs of all loaded plugins.
+  # I chose to make each of these commands as a separate function because:
-plugin-list() {
+  # 1. automatic completion
+  # 2. automatic correction
+  # 3. hyphen is a single keystroke, just like space, so `zplg-list` is not
+  #    hard to type fast.
+
+  # Prints IDs of all loaded plugins.
+  zplg-list() {
     # (F) modifier joins an array with newlines
     print "${(F)ZPLG_LOADED_PLUGINS}"
-}
+  }
 
-# Upgrades all plugins if no arguments are given, otherwise upgrades plugins by
+  # Upgrades all plugins if no arguments are given, otherwise upgrades plugins by
-# their IDs.
+  # their IDs.
-plugin-upgrade() {
+  zplg-upgrade() {
     local plugin_ids_var
     if (( $# > 0 )); then
       plugin_ids_var="@"
@@ -408,7 +417,7 @@ plugin-upgrade() {
     fi
 
     local plugin_id plugin_url plugin_from plugin_dir; local -a plugin_build
-  # for description of the (P) modifier see _zplg_run_commands
+    # for description of the (P) modifier see `_zplg_run_commands`
     for plugin_id in "${(@P)plugin_ids_var}"; do
       if ! _zplg_is_plugin_loaded "$plugin_id"; then
         _zplg_error "unknown plugin $plugin_id"
@@ -433,10 +442,10 @@ plugin-upgrade() {
         ( cd "$plugin_dir" && _zplg_run_commands plugin_build ) || return "$?"
       fi
     done
-}
+  }
 
-# Reinstall plugins by IDs.
+  # Reinstall plugins by IDs.
-plugin-reinstall() {
+  zplg-reinstall() {
     if (( $# == 0 )); then
       _zplg_error "usage: $0 <plugin...>"
       return 1
@@ -461,16 +470,16 @@ plugin-reinstall() {
 
       if (( ${+ZPLG_LOADED_PLUGIN_BUILD_CMDS[$plugin_id]} )); then
         # for description of this terrible hack see the ending of the
-      # `plugin-upgrade` function
+        # `zplg-upgrade` function
         plugin_build=("${(@Q)${(z)${ZPLG_LOADED_PLUGIN_BUILD_CMDS[$plugin_id]}}}")
         _zplg_log "building $plugin_id"
         ( cd "$plugin_dir" && _zplg_run_commands plugin_build ) || return "$?"
       fi
     done
-}
+  }
 
-# Clears directories of plugins by their IDs.
+  # Clears directories of plugins by their IDs.
-plugin-purge() {
+  zplg-purge() {
     if (( $# == 0 )); then
       _zplg_error "usage: $0 <plugin...>"
       return 1
@@ -487,4 +496,6 @@ plugin-purge() {
       _zplg_log "removing $plugin_id"
       rm -rf "$plugin_dir"
     done
-}
+  }
+
+# }}}