From 89db40a55275b2086e873d322013c98c14b68cfe Mon Sep 17 00:00:00 2001
From: Masataro Asai <guicho2.71828@gmail.com>
Date: Sat, 26 Oct 2019 12:10:31 -0400
Subject: [PATCH] [README] tutorial for CLI / REPL commands

---
 README.md | 116 ++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 83 insertions(+), 33 deletions(-)

diff --git a/README.md b/README.md
index 01a5045..e330f58 100644
--- a/README.md
+++ b/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
-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.
+Step 2: Initialize your blog repository.
 
-1. Install a Common Lisp implementation (we recommend SBCL) and
-   [Quicklisp](http://quicklisp.org/).
-2. Place a config file for coleslaw in your `$HOME` directory. If you
-   want to run multiple blogs with coleslaw, you can keep each blog's
-   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]
-   to create one from scratch.
-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.
+``` sh
+$ mkdir yourblog ; cd yourblog
+$ git init
+$ coleslaw setup
+```
+``` lisp
+(coleslaw-cli:setup)
+```
 
-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
-[conf_docs]: https://github.com/redline6561/coleslaw/blob/master/docs/config.md
-[post_hook]: https://github.com/redline6561/coleslaw/blob/master/examples/example.post-receive
+``` sh
+$ coleslaw new
+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
-pages, etc.)
+of the content. (I.e. `.post` for blog posts, `.page` for static 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