Improve docs

docs/cli/install.adoc

@@ -1,18 +1,23 @@
 Install one or more packages.
 
 == USAGE
+  omf install <spec> [<spec> [...]]    Install package by name or URL
   omf install                          Install missing packages from bundle
-  omf install (<name> | <url>)         Install package by name or URL
 
 == DESCRIPTION
-You can install packages directly by URL via omf install URL.
+Installs packages identified by each <spec> given. A package can be specified either by name or by a URL.
 
-When called without arguments, install missing packages from bundle.
+When specifying a package by name, the package name is searched for in each package repository currently installed. The first matching package is selected and downloaded. See `omf help repositories` for more information about repositories.
+
+When a package is specified by URL, OMF assumes the URL points to a Git repository and installs the package by cloning the repository.
+
+When called without arguments, any packages specified in your bundle file that are missing will be installed.
 
 == EXAMPLES
-  omf install
   omf install brew
   omf install https://github.com/oh-my-fish/plugin-brew
+  omf install brew spark
+  omf install
 
 == ALIASES
 *omf i*, *omf in*, *omf get*

docs/cli/new.adoc

@@ -1,10 +1,13 @@
 Create a new package from a template.
 
 == USAGE
-  omf new (_pkg_ | _theme_) <name>
+  omf new (_plugin_ | _theme_) <name>
+
+== DESCRIPTION
+Creates a new package skeleton under `$OMF_CONFIG` named <name>. The type of package is determined by the first argument.
 
 == EXAMPLES
-  omf new pkg mypkg
+  omf new plugin myplugin
   omf new theme mytheme
 
 == ALIASES

docs/cli/omf.adoc

@@ -7,20 +7,20 @@ Oh My Fish! - the fish shell framework
 Provides options to list, download and remove packages, update the framework, create a new package, etc.
 
 == COMMANDS
-<<cd.adoc#,**cd**>>::            Change directory to plugin/theme directory.
+<<cd.adoc#,**cd**>>::            Change to root or package directory.
 <<channel.adoc#,**channel**>>::       Get or change the update channel.
 <<describe.adoc#,**d**escribe>>::      Show information about a package.
 <<destroy.adoc#,**destroy**>>::       Uninstall Oh My Fish.
 <<doctor.adoc#,**doctor**>>::        Troubleshoot Oh My Fish.
-<<help.adoc#,**help**>>::          Shows help about a specific action.
+<<help.adoc#,**help**>>::          Shows help about a command.
 <<install.adoc#,**i**nstall>>::       Install one or more packages.
 <<list.adoc#,**l**ist>>::          List installed packages.
 <<new.adoc#,**n**ew>>::           Create a new package from a template.
 <<reload.adoc#,**reload**>>::        Reload the current shell.
-<<remove.adoc#,**r**emove>>::        Remove a theme or package.
+<<remove.adoc#,**r**emove>>::        Remove a package.
 <<repositories.adoc#,**repo**sitories>>::  Manage package repositories.
 <<search.adoc#,**s**earch>>::        Search for a package or theme.
-<<theme.adoc#,**t**heme>>::         List / Use themes.
+<<theme.adoc#,**t**heme>>::         Install and list themes.
 <<update.adoc#,**u**pdate>>::        Update Oh My Fish.
 <<version.adoc#,**version**>>::       Display version and exit.
 

docs/cli/reload.adoc

@@ -4,4 +4,6 @@ Reload the current shell.
   omf reload
 
 == DESCRIPTION
-Reload Oh My Fish and all plugins by using `exec` to replace current shell process with a brand new process. This command tries to be as safe as possible, mitigating side-effects caused by exec and preventing the reload in case of background processes.
+Reload Oh My Fish and all plugins by using `exec` to replace current shell process with a brand new process.
+
+This command tries to be as safe as possible, mitigating side-effects caused by exec and preventing the reload in case of background processes.

docs/cli/remove.adoc

@@ -3,6 +3,9 @@ Remove a package.
 == USAGE
   omf remove <package>
 
+== DESCRIPTION
+Removes an installed package identified by <package>.
+
 == EXAMPLES
   omf remove brew
   omf remove l

docs/cli/repositories.adoc

@@ -6,14 +6,16 @@ Manage user-installed package repositories.
   omf repositories (rm | remove) <url> [<branch>]
 
 == DESCRIPTION
-Package repositories are where packages come from used by commands like omf install. By default the official repository is always installed and available.
+Provides commands for viewing and managing package repositories for the current user.
+
+Package repositories are where named packages come from used by commands like `omf install`. By default the official repository is always installed and available.
 
 == SUBCOMMANDS
 list, ls::
   List installed repositories.
 
 add::
-  Add a package repository.
+  Add a package repository located at <url>. If <branch> is not specified, the default branch of `master` is assumed.
 
 remove, rm::
   Remove a package repository.

docs/cli/update.adoc

@@ -1,14 +1,18 @@
-Update Oh My Fish.
+Update Oh My Fish and packages.
 
 == USAGE
   omf update [<package1> [<package2> [...]]]
 
 == DESCRIPTION
-Update Oh My Fish, all package repositories, and all installed packages.
+Updates Oh My Fish, package repositories, and installed packages.
 
-* When called without arguments, updates the core framework and all installed packages.
-* You can choose to update only the core, by running `omf update omf`.
-* For selective package update, list only the names of packages you wish to update. You may still include "omf" in the list to update the core as well.
+Each package name that is given will be updated. For example, to update the packages `bobthefish` and `direnv`, run:
+
+  omf update bobthefish direnv
+
+The special package name `omf` will cause Oh My Fish to update itself. This can be combined with other package names.
+
+If no arguments are given, all installed packages will be updated along with Oh My Fish.
 
 == ALIASES
 *omf u*, *omf up*