[README] tutorial for CLI / REPL commands

README.md

@@ -36,48 +36,84 @@ testing is primarily done on [SBCL](http://www.sbcl.org/) and [CCL](http://ccl.c
 | [Pygments](http://pygments.org/)                       | [colorize](http://www.cliki.net/colorize)    |                                                       |
 
 
-## Installation
+## Installation/Tutorial
+
+<!-- Don't let the first user select from multiple choises -->
+
+Step 1: Install this library.
+
+With [Roswell](https://roswell.github.io/),
+``` sh
+$ ros install coleslaw
+$ export PATH="$HOME/.roswell/bin:$PATH" # If you haven't done this before
+```
+
+or
+
+``` lisp
+(ql:quickload :coleslaw-cli)
+```
 
 
-Coleslaw can either be run **manually** on a local machine or
+Step 2: Initialize your blog repository.
-triggered **automatically** on git push to a server.  If you want a
-server install, run these commands on your server _after_ setting up a
-[git bare repo](http://git-scm.com/book/en/Git-on-the-Server-Setting-Up-the-Server).
-Otherwise, run the commands on your local machine.
 
-1. Install a Common Lisp implementation (we recommend SBCL) and
+``` sh
-   [Quicklisp](http://quicklisp.org/).
+$ mkdir yourblog ; cd yourblog
-2. Place a config file for coleslaw in your `$HOME` directory. If you
+$ git init
-   want to run multiple blogs with coleslaw, you can keep each blog's
+$ coleslaw setup
-   config file in that blog's repo.  Feel free to copy and edit the
+```
-   [example config][ex_config] or consult the [config docs][conf_docs]
+``` lisp
-   to create one from scratch.
+(coleslaw-cli:setup)
-3. This step depends on whether you're setting up a local or server install.
+```
-   * Server Install: Copy and `chmod +x` the
-     [example post-receive hook][post_hook] to your blog's bare repo.
-   * Local Install:  Just run the following commands in the
-     REPL whenever you're ready to regenerate your blog:
-     ```
-     (ql:quickload :coleslaw)
-     (coleslaw:main "/path/to/my/blog/")
-     ```
-4. Optionally, point the web server of your liking at your config-specified
-   `:deploy-dir`. Or "deploy-dir/.curr" if the `versioned` plugin is enabled.
-5. If you use Emacs, consider installing
-   [coleslaw-mode](https://github.com/equwal/coleslaw-mode) to author your
-   posts.
 
-Now just write posts, git commit and build by hand or by push.
+Step 3: Write a post file in the current directory.
+The file should contain a certain metadata, so use the `coleslaw new` command,
+which instantiates a correct file for you.
 
-[ex_config]: https://github.com/redline6561/coleslaw/blob/master/examples/example.coleslawrc
+``` sh
-[conf_docs]: https://github.com/redline6561/coleslaw/blob/master/docs/config.md
+$ coleslaw new
-[post_hook]: https://github.com/redline6561/coleslaw/blob/master/examples/example.post-receive
+Created a post 2017-11-06.post .
+```
+``` lisp
+(coleslaw-cli:new "post")
+```
+
+Step 4: Generate the site from those post files.
+The result goes to the `deploy/` subdirectory.
+
+``` sh
+$ coleslaw
+```
+``` lisp
+(coleslaw-cli:generate)
+```
+
+Step 5: You can also launch a server...
+
+``` sh
+$ coleslaw preview
+```
+``` lisp
+(coleslaw-cli:preview)
+```
+
+Step 6: and watch the file system to automatically regenerate the site!
+
+``` sh
+$ coleslaw watch          # or even better,
+$ coleslaw watch-preview 
+```
+``` lisp
+(coleslaw-cli:watch)      ;; watch-preview does not work on REPL right now
+```
+
+For further customization, edit the `.coleslawrc` file generated by `coleslaw setup`.
+Consult the [config docs](https://github.com/redline6561/coleslaw/blob/master/docs/config.md).
 
 ## The Content Format
 
 Coleslaw expects content to have a file extension matching the class
-of the content. (I.e. `.post` for blog posts, `.page` for static
+of the content. (I.e. `.post` for blog posts, `.page` for static pages, etc.)
-pages, etc.)
 
 There should also be a metadata header on all files
 starting and ending with the config-specified `:separator`, ";;;;;" by
@@ -108,6 +144,20 @@ Two themes are provided: hyde, the default, and readable (based on
 A guide to creating themes for coleslaw lives
 [here](https://github.com/redline6561/coleslaw/blob/master/docs/themes.md).
 
+## Deploying on a standalone server
+
+Coleslaw can deploy to a standalone server.
+If you want this server installation, initialize a bare git repo and
+set up the post-receive hook on that repo.
+
+* First initialize a [git bare repo](http://git-scm.com/book/en/Git-on-the-Server-Setting-Up-the-Server) on the server.
+* Copy [example post-receive hook][post_hook] to your blog's bare repo and set the executable bit (`chmod +x`).
+
+* Point the web server at `:deploy-dir` attribute on the config file.
+  Or "deploy-dir/.curr" if the `versioned` plugin is enabled.
+
+[post_hook]: https://github.com/redline6561/coleslaw/blob/master/examples/example.post-receive
+
 ## Hacking
 
 A core goal of *coleslaw* is to be both pleasant to read and easy to