Update lisp docs
diff --git a/doc/_static/custom.css b/doc/_static/custom.css
new file mode 100644
index 0000000..f474a3e
--- /dev/null
+++ b/doc/_static/custom.css
@@ -0,0 +1,3 @@
+.pre {
+ font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;
+}
diff --git a/doc/conf.py b/doc/conf.py
index dd82eb7..39e52ea 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -30,3 +30,6 @@
html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']
+
+def setup(app):
+ app.add_stylesheet('custom.css')
diff --git a/doc/lisp-std.rst b/doc/lisp-std.rst
index f317f10..1d00ce0 100644
--- a/doc/lisp-std.rst
+++ b/doc/lisp-std.rst
@@ -8,6 +8,57 @@
In general every user-facing API in the standard library should be documented
here.
+- ``(x ...)`` represents a list ``x``.
+- ``& body`` means that the rest of the list is represented by ``body``.
+- ``[something]`` means that ``something`` is optional.
+
+Top-level primitives
+--------------------
+
+These are "functions" that can only appear at the top-level of the program. This
+means they can't be nested in any other expressions.
+
+.. function:: (defun function-name (args ...) & body)
+
+ Defines a function ``function-name`` that takes ``args`` and evaluates
+ ``body``. ``function-name`` is quoted, not evaluated.
+
+ .. code-block:: lisp
+
+ (defun say-hi (name)
+ (print "Hi, ")
+ (print name))
+
+ (say-hi "Joe")
+ ; "Hi,"
+ ; "Joe"
+
+.. function:: (defmacro macro-name (args ...) & body)
+
+ ``defmacro`` is to macros as ``defun`` is to functions. When ``macro-name``
+ is called, whatever it evaluates to will be compiled.
+
+ Note that internally this compiles a function the same way all other
+ functions are compiled, meaning you can call **any** lisp function from a
+ macro definition and it will work as expected.
+
+ .. code-block:: Lisp
+
+ (defun double (n)
+ (+ n n))
+
+ (defmacro call-with-4 (whatever)
+ (print "this was run at **compile time**")
+ (print whatever)
+ ;; ``whatever`` expands to the form passed to this macro, in this case
+ ;; ``double``.
+ (list whatever 4))
+
+ (print (call-with-4 double))
+ ; "this was run at **compile time**"
+ ; 'double
+ ; 8
+
Functions
---------
@@ -37,10 +88,18 @@
Return the first item in ``pair``.
+ .. code-block:: lisp
+
+ (car (cons 'a 'b)) ;=> 'a
+
.. function:: (cdr pair)
Return the second (last) item in ``pair``.
+ .. code-block:: lisp
+
+ (cdr (cons 'a 'b)) ;=> 'b
+
.. function:: (cons a b)
Return a cons-pair containing ``a`` and ``b``.
@@ -54,12 +113,17 @@
Returns a cons-list of items.
+ .. code-block:: lisp
+
+ (list 1 2 3)
+ ; is the same as
+ (cons 1 (cons 2 (cons 3 nil)))
+
.. function:: (quote form)
Returns form without evaluating it.
.. code-block:: lisp
- '(cons a b)
'(cons a b)
; or