docs: Revamp and update Docs

Author: hyperupcall

README.md

@@ -4,16 +4,14 @@
 
 ---
 
+STATUS: ALPHA
+
 `bpm` is a fork of [basher](https://github.com/basherpm/basher) that adds a _ton_ of new functionality. It makes it significantly easier to install Bash, Zsh, etc. projects to your computer. Often, these projects / scripts are _not_ available through official `apt`, `DNF`, `pacman` repositories, or even from unofficial sources like third party apt repositories or the [AUR](https://aur.archlinux.org)
 
-Let's say you want to install [rupa/z](https://github.com/rupa/z), [tj/git-extras](https://github.com/tj/git-extras), [aristocratos/bashtop](https://github.com/aristocratos/bashtop), and [JosefZIla/bash2048](https://github.com/JosefZIla/bash2048). Simply run the following (as you can see, many formats are supported)
+Let's say you want to install [rupa/z](https://github.com/rupa/z), [tj/git-extras](https://github.com/tj/git-extras), [aristocratos/bashtop](https://github.com/aristocratos/bashtop), and [JosefZIla/bash2048](https://github.com/JosefZIla/bash2048). Simply run the following
 
 ```sh
-$ bpm add \
-  rupa/z \
-  github.com/tj/git-extras \
-  https://github.com/aristocratos/bashtop \
-  git@github.com:JosefZIla/bash2048
+$ bpm add rupa/z tj/git-extras aristocratos/bashtop JosefZIla/bash2048
 ```
 
 This symlinks all executable scripts to a common directory. It does this for completion files and man pages as well
@@ -27,57 +25,22 @@ $ ls -l --color=always ~/.local/share/bpm/cellar/bin/
 ...
 ```
 
-If you want to automatically add the bin directory to your path, source the completion files, and add the man pages to your man path, simply add a two-liner in your shell configuration
+To be able to access the binaries, completion files, and man pages in your shell, simply add a two-liner in your shell configuration
 
 ```sh
+# ~/.bashrc
 export PATH="${XDG_DATA_HOME:-$HOME/.local/share}/bpm/source/pkg/bin:$PATH"
-eval "$(bpm init bash)" # replace 'bash' with your shell
+eval "$(bpm init bash)" # zsh and fish are also supported
 ```
 
-STATUS: ALPHA
-
-See [Getting Started](./docs/getting-started.md) for more details
-
-## Local Package Development
-
-If you are working on a project, and want to pull in a dependency, say [bash-args](https://github.com/eankeen/bash-args), the workflow looks like this
-
-To use the packages, simply append to the `PATH` variable in your script entrypoint (script.sh in the example below). Note that exporting it isn't required because it's already an exported variable
-
-```sh
-mkdir 'my-project' && cd 'my-project'
-
-# Creating a 'bpm.toml' is required so bpm knows where
-# the root of the project is
-touch 'bpm.toml'
-
-bpm add 'eankeen/bash-args'
-
-cat > 'script.sh' <<-"OUTEREOF"
-#!/usr/bin/env bash
-
-PATH="$PWD/bpm_packages/bin:$PATH"
-
-declare -A args=()
-
-# 'bash-args' requires that we use `source`
-source bash-args parse "$@" <<-"EOF"
-@flag [port.p] {3000} - The port to open on
-EOF
-
-echo "Using port '${args[port]}'"
-OUTEREOF
-
-chmod +x './script.sh'
-./script.sh # Using port '3000'
-./script.sh --port 4000 # Using port '4000'
-```
+See [Installation](./docs/installation.md) and [Getting Started](./docs/getting-started.md) for more details
 
 ## Alternatives Comparison
 
 Why not use `bpkg` or `Basher`? Because `bpm`...
 
 - Can install multiple packages at once
+- Install local dependencies for a particular project (bpkg and basher)
 - Does not use a `package.json` that clobbers with NPM's `package.json` (bpkg)
 - Does not automatically invoke `make` commands on your behalf (bpkg)
 - Does not automatically source a `package.sh` for package configuration (basher)
@@ -88,5 +51,6 @@ Why not use `bpkg` or `Basher`? Because `bpm`...
 - Prints why a command failed, rather than just printing the help menu (basher)
 - Better bpm completion scripts
 - More flexibly parses command line arguments (basher)
+- Install local directories as packages (bpkg)
 
-I originally created a [different](https://github.com/eankeen/shell-installer) Shell package manager but later abandoned it. When I _really_ needed the functionality, I forked Basher because it had an excellent test suite and its behavior for installing packages actually made sense, compared to `bpkg`
+I I forked Basher because it had an excellent test suite and its behavior for installing packages made more sense to me, compared to `bpkg`

docs/getting-started.md

@@ -1,59 +1,102 @@
 # Getting Started
 
-## Installation
+Succinctly, bpm is a fancy combination of `git clone` and `ln -s`. It clones a repositories, and puts all of its man pages, completion scripts, and binaries in common folders. Let's see it in action
 
-STATUS: IN DEVELOPMENT
+## Installing a simple package
 
-`bpm` requires `bash >= 4.3`, and the `realpath` utility from `coreutils`. On
-osx you can install both with brew:
+For this demonstration, we're going to install and use [bash2048](JosefZIla/bash2048). Note that this will still work, even if Zsh or Fish is your default shell
 
 ```sh
-brew install bash coreutils
+bpm --global add github.com/JosefZIla/bash2048
 ```
 
-1. Clone `bpm`
+That's it - now you can use it!
 
-  ```sh
-  git clone https://github.com/bpmpm/bpm "${XDG_DATA_HOME:-$HOME/.local/share}/bpm/source"
-  ```
+```sh
+$ bash2048.sh
+Bash 2048 v1.1 (https://github.com/mydzor/bash2048) pieces=6 target=2048 score=60
 
-2. Initialize `bpm` in your shell initialization
+/------+------+------+------\
+|      |      |      |      |
+|------+------+------+------|
+|    4 |      |      |      |
+|------+------+------+------|
+|    2 |    2 |      |      |
+|------+------+------+------|
+|   16 |    8 |      |    2 |
+\------+------+------+------/
+```
 
-  For `bash`, `zsh`, `sh`
+## Install a Bash function
 
-  ```sh
-  export PATH="${XDG_DATA_HOME:-$HOME/.local/share}/bpm/source/pkg/bin:$PATH"
-  eval "$(bpm init bash)" # replace 'bash' with your shell
-  ```
+For the second demonstration, we're going to install [z](https://github.com/rupa/z). If you already have it installed, don't worry - it will be installed to a different location and you can remove it separately
 
-  For `fish`
+```sh
+# Globally install z
+bpm --global add rupa/z
+```
 
-  ```fish
-  set -gx PATH "${XDG_DATA_HOME:-$HOME/.local/share}/bpm/source/pkg/bin" $PATH
-  status --is-interactive; and . (bpm init fish | psub)
-  ```
+As you can see, if you do not include the domain, it automatically uses github.com
 
+This clones `z` to `$HOME/.local/share/bpm/cellar/packages/github.com/rupa/z`
 
-## Updating
+It adds a symlink from the repository's `z.1` man page to `$HOME/.local/share/bpm/cellar/man/man1/z.1`
 
-Go to the directory where you cloned bpm and pull the latest changes
+Now, (assuming you completed [Installation](./installation.md) properly), you can display the manual right away
 
 ```sh
-cd "${XDG_DATA_HOME:-$HOME/.local/share}/bpm/source"
-git pull
+man z
 ```
 
+You might also try to execute `z.sh`
+
 ```sh
-$ bash2048.sh
-Bash 2048 v1.1 (https://github.com/mydzor/bash2048) pieces=6 target=2048 score=60
+$ z
+bash: z: command not found
+$ z.sh
+bash: z.sh: command not found
+```
 
-/------+------+------+------\
-|      |      |      |      |
-|------+------+------+------|
-|    4 |      |      |      |
-|------+------+------+------|
-|    2 |    2 |      |      |
-|------+------+------+------|
-|   16 |    8 |      |    2 |
-\------+------+------+------/
+But it doesn't work - this is standard behavior. When looking for binaries, bpm _does_ look at the root directory, but only symlinks shell scripts that are marked as _executable_ (`chmod +x z.sh`)
+
+The authors of `z` did not mark the file as executable because they did not intend for you to execute the file - you are supposed to `source` it. This is why the `package-path` command exists:
+
+```sh
+$ bpm --global package-path z.sh
+/home/username/bpm/cellar/packages/rupa/z
+```
+
+Now, use the `package-path` to source `z.sh`. Note that `z.sh` only supports either Bash or Zsh, so you need to currently be in one of those shells for this to work
+
+```sh
+$ source "$(bpm --global package-path rupa/z)/z.sh"
+$ z
+common:    /tmp/tmp.MBF063fdlK/completions
+29988      /tmp/tmp.MBF063fdlK/completions
 ```
+
+Note that if `z` does not show output, that's normal. You may need to `cd` to some directories to build the database
+
+If you want to do this persistantly, just add this to your `~/.bashrc` (or `~/.zshrc`).
+
+## Remove packages
+
+If you completed boht previous steps, two packages should be installed
+```sh
+$ bpm --global list
+github.com/JosefZIla/bash2048
+github.com/rupa/z
+```
+
+Remove them with `remove`
+
+```sh
+$ bpm --global remove \
+  git@github.com:JosefZIla/bash2048 \
+  https://github.com/rupa/z
+$ bpm --global list
+```
+
+Note that we specified the SSH URL and the HTTPS URL when removing. You can specify the package this way with all commands, including the `add`, `package-path`, and `upgrade` commands
+
+And you are done! To learn more, see [Recepies](./.recepies.md), [Reference](./reference.md), or [Tips](./tips.md)

docs/installation.md

@@ -0,0 +1,46 @@
+# Installation
+
+## Prerequisites
+
+- `bash >= 4.3`
+- GNU coreutils
+
+If you are on macOS, you need to install the latest `bash` and `coreutils`:
+
+```sh
+# Install prerequisite packages
+brew install bash coreutils
+```
+
+See the full list of supported operating systems in [Support](./support.md)
+
+## Install
+
+##### 1. Clone `bpm`
+
+```sh
+git clone https://github.com/bpmpm/bpm "${XDG_DATA_HOME:-$HOME/.local/share}/bpm/source"
+```
+
+By default, this installs bpm to `$HOME/.local/share/bpm/source`
+
+##### 2. Add initialization script to shell profile
+
+This enables bpm to automatically setup your `PATH`, set completion variables, source completion files, and other things
+
+
+For `bash`, `zsh`, `sh`
+
+```sh
+export PATH="${XDG_DATA_HOME:-$HOME/.local/share}/bpm/source/pkg/bin:$PATH"
+eval "$(bpm init bash)" # replace 'bash' with your shell
+```
+
+For `fish`
+
+```fish
+set -gx PATH "${XDG_DATA_HOME:-$HOME/.local/share}/bpm/source/pkg/bin" $PATH
+status --is-interactive; and . (bpm init fish | psub)
+```
+
+And now you're done! Move on to [Getting Started](./getting-started.md) to learn the basics