Update README.md

README.md

@@ -1,11 +1,81 @@
-# run(.fish)
+# swim.fish
 
-This repo contains my run(.fish) script. It serves as a central place to store and document commands
-related to a project. It was written with the KISS principle at the forefront of my mind. New
-versions will only ever be simple enough to understand almost immediately.
+swim.fish is a simple executable script and fish-based "DSL". It lets you easily compile and catalog
+your project's most frequently run commands. Think `make` or `npm run`.
 
-In this repo is a hello world example. You can just copy this script to your repo and replace it's
-command functions with your own. You're encouraged to modify it to your needs, but I urge you to
-keep the KISS principle in mind as well. Shell scripts have a way of getting away from you (who
-knew?).
+## Table of Contents
 
+- [Getting Started](#swim-fish#getting-started)
+- [Install `sw`](#swim-fish#install-sw)
+- [Included Commands](#swim-fish#included-commands)
+- [Self-executable swim.fish](#swim-fish#self-executable-swim-fish)
+
+## Getting Started
+
+[*^ Back to Top ^*](#swim-fish)
+
+The easiest way to get started is by copy this repository's `swim.fish` to your own project's root
+directory. Then replace this projects command functions with your own. They look like this:
+
+```fish
+function swim_your_command_name -a one_of n_args -d 'A sentence description of your command'
+    fish shell content
+    ...
+end
+```
+
+The required prefix of `swim_` can be configured, by setting the `cmd_func_prefix` global variable
+(located at the top of example swim.fish).
+
+## Install `sw`
+
+[*^ Back to Top ^*](#swim-fish)
+
+The only dependency is [fish itself](https://fishshell.com/).
+
+The easiest way to install `sw` is by running this
+
+`curl -fsS https://raw.githubusercontent.com/mitchell/swim.fish/master/sw >sw && chmod +x sw`
+
+then copying `sw` to your preferred location in your binpath, like `/usr/local/bin` on .
+
+## Included Commands
+
+[*^ Back to Top ^*](#swim-fish)
+
+The following commands are included.
+
+- `help`:
+  - Examples:
+    - `sw help`: Displays all top-level commands and their descriptions
+    - `sw help <command>`: Displays the commands definition
+    - `sw <command group> help`: Displays the group's commands and their descr
+  - Aliases:
+    - `--help`: If used with command group display group help, otherwise display command definition.
+    - `-h`: Same as above
+- `do`:
+  - Examples:
+    - `sw do <command> [arg ...], <command> [arg ...], ...`: Run the specified commands in sequence
+
+
+## Self-executable swim.fish
+
+[*^ Back to Top ^*](#swim-fish)
+
+If you wish to make your *swim.fish* file self-executable instead of installed `sw`. Then all you
+have to do is add
+
+```fish
+#!/usr/bin/env fish
+```
+
+to the top of your *swim.fish*, and
+
+```fish
+curl -fsS https://raw.githubusercontent.com/mitchell/swim.fish/master/importable_sw.fish | source
+run_swim_command $cmd_func_prefix $argv
+```
+
+to the bottom of your file.
+
+Then you can run it like `./swim.fish <command>`.

swim.fish

@@ -74,4 +74,4 @@ function swim_fails -d 'This command fails every time'
 end
 
 #curl -fsS https://raw.githubusercontent.com/mitchell/swim.fish/master/importable_sw.fish | source
-#run_swim_command 'swim' $argv
+#run_swim_command $cmd_func_prefix $argv