From 883c109f390fc2c33d4701b65c0ab74bc2aed1a3 Mon Sep 17 00:00:00 2001
From: vindarel <vindarel@mailz.org>
Date: Mon, 7 Dec 2020 13:18:08 +0100
Subject: [PATCH] docs: each section its page and sub-sidebar

---
 docs/README.md   | 56 +--------------------------
 docs/_sidebar.md |  6 +++
 docs/index.html  |  3 +-
 docs/install.md  | 98 ++++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 107 insertions(+), 56 deletions(-)
 create mode 100644 docs/_sidebar.md
 create mode 100644 docs/install.md

diff --git a/docs/README.md b/docs/README.md
index e3337b5..4ed0e30 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -8,57 +8,7 @@ Questions, doubts? See the [FAQ](FAQ.md).
 
 # Install
 
-## With Quicklisp
-
-You need a Lisp implementation and Quicklisp installed.
-
-CIEL is not yet on Quicklisp (but it is on [Ultralisp](https://ultralisp.org)), so clone this repository and load the .asd (with `load` or `C-c C-k` in Slime).
-
-``` example
-git clone https://github.com/ciel-lang/CIEL ~/quicklisp/local-projects/CIEL
-```
-
-Then, quickload it:
-
-```lisp
-(ql:quickload "ciel")
-```
-
-and enter the `ciel-user` package, instead of the default `common-lisp-user` (or `cl-user`):
-
-```lisp
-(in-package :ciel-user)
-```
-
-## With a core image
-
-You need a Lisp implementation, but you don't need Quicklisp.
-
-Build a *core image* for your lisp with all CIEL's dependencies:
-
-``` example
-sbcl --load build-image.lisp
-```
-
-and use it:
-
-``` example
-sbcl --core ciel --eval '(in-package :ciel-user)'
-```
-
-TODO: we will distribute ready-to-use core images.
-
-## With a binary
-
-You don't need anything, just download the CIEL executable and run its REPL.
-
-TODO: build it on CI for different platforms.
-
-To build it, clone this repository and run `make build`.
-
-Start it with `./ciel-repl`.
-
-You are dropped into a custom Lisp REPL.
+See the [installation instructions](install.md).
 
 # CIEL's custom REPL
 
@@ -986,10 +936,6 @@ Example:
    (…))
 ```
 
-# FAQ
-
-See it here: [FAQ](FAQ.md).
-
 # Final words
 
 That was your life in CL:
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
new file mode 100644
index 0000000..5dccf7b
--- /dev/null
+++ b/docs/_sidebar.md
@@ -0,0 +1,6 @@
+
+* [Home](/)
+* [Install](install.md)
+* [Libraries](libraries.md)
+* [Language extensions](language-extensions.md)
+* [FAQ](FAQ.md)
diff --git a/docs/index.html b/docs/index.html
index d8b3c38..6391b5c 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -22,7 +22,8 @@
       coverpage: true,
       coverpage: ['/', '/fr/'],
       auto2top: true,
-
+      loadSidebar: true,
+      subMaxLevel: 2
     }
   </script>
   <!-- <script src="//unpkg.com/docsify/lib/docsify.min.js"></script> -->
diff --git a/docs/install.md b/docs/install.md
new file mode 100644
index 0000000..43ed8ea
--- /dev/null
+++ b/docs/install.md
@@ -0,0 +1,98 @@
+
+# Install
+
+## With Quicklisp
+
+You need a Lisp implementation and Quicklisp installed.
+
+CIEL is not yet on Quicklisp (but it is on [Ultralisp](https://ultralisp.org)), so clone this repository and load the .asd (with `load` or `C-c C-k` in Slime).
+
+``` example
+git clone https://github.com/ciel-lang/CIEL ~/quicklisp/local-projects/CIEL
+```
+
+Then, quickload it:
+
+``` commonlisp
+(ql:quickload "ciel")
+```
+
+and enter the `ciel-user` package, instead of the default `common-lisp-user` (or `cl-user`):
+
+``` commonlisp
+(in-package :ciel-user)
+```
+
+## With a core image
+
+You need a Lisp implementation, but you don't need Quicklisp.
+
+Build a *core image* for your lisp with all CIEL's dependencies:
+
+``` example
+sbcl --load build-image.lisp
+```
+
+and use it:
+
+``` example
+sbcl --core ciel --eval '(in-package :ciel-user)'
+```
+
+TODO: we will distribute ready-to-use core images.
+
+## With a binary. Use CIEL's custom REPL.
+
+You don't need anything, just download the CIEL executable and run its REPL.
+
+TODO: build it on CI for different platforms.
+
+To build it, clone this repository and run `make build`.
+
+Start it with `./ciel-repl`.
+
+You are dropped into a custom Lisp REPL, freely based on [sbcli](https://github.com/hellerve/sbcli).
+
+This REPL is more user friendly than the default SBCL one:
+
+-   it has readline capabilities, meaning that the arrow keys work by default (wouhou!) and there is a persistent history, like in any shell.
+-   it has **multiline input**.
+-   it has **TAB completion**.
+-   it handles errors gracefully: you are not dropped into the debugger and its sub-REPL, you simply see the error message.
+-   it has optional **syntax highlighting**.
+
+    It also defines short helper commands:
+
+``` txt
+
+:help => Prints this general help message
+:doc => Prints the available documentation for this symbol
+:? => Gets help on a symbol <sym>: :? str
+:w => Writes the current session to a file <filename>
+:d => Dumps the disassembly of a symbol <sym>
+:t => Prints the type of a expression <expr>
+:q => Ends the session.
+```
+
+Note: the documentation is also available by appending a "?" after a function name:
+
+``` txt
+ciel-user> (dict ?
+```
+
+Syntax highlighting is currently off by default. To enable it, install [pygments](https://pygments.org/) and add this in your `~/.cielrc`:
+
+``` commonlisp
+(in-package :sbcli)
+(setf *syntax-highlighting* t)
+
+;; and, optionally:
+;; (setf *pygmentize* "/path/to/pygmentize")
+;; (setf *pygmentize-options* (list "-s" "-l" "lisp"))
+```
+
+You can also switch it on and off from the REPL:
+
+``` commonlisp
+(setf sbcli:*syntax-highlighting* t)
+```