Skip to content

A peer-to-peer stack for code collaboration

feat(docs): Update docs (#612)

James Haydon2b64883b4f90
diff --git a/docs/source/guide/Basics.lrad b/docs/source/guide/Basics.lrad
index 3fb5bbe..a5227ff 100644
--- a/docs/source/guide/Basics.lrad
+++ b/docs/source/guide/Basics.lrad
@@ -1,16 +1,28 @@
# Basics
Though `radicle` is designed with a particular use-case in mind--namely,
-defining and interacting with the Open Source Network chains--it is ultimately a
+defining and interacting with decentralised state machines--it is ultimately a
general purpose language, quite similar to
[Scheme](en.wikipedia.org/wiki/Scheme_%28programming_language%29) or
-[Clojure](clojure.org/). To effectively use it, it is helpful to learn the basics
-of it independent of its application.
+[Clojure](clojure.org/). To effectively use it, it is helpful to learn the
+basics of it independent of its application.
This chapter introduces `radicle` as a language. In each section we present
a core datatype of the language, and show some basic operations that can be
performed on them.
+## Comments
+
+The string `;;` starts a comment. This comments all the text until the next
+line-break. In this guide we will often add a comment as follows:
+
+```radicle
+(+ 1 1) ;; ==> 2
+```
+
+to indicate that an expression (in this case `(+ 1 1)`) evaluates to a specific
+value (in this case `2`).
+
## Built-in datatypes
`radicle` supports the following datatypes:
@@ -32,6 +44,30 @@ Strings are enclosed in double quotes:
"this is a string"
```
+### Keywords
+
+Keywords are identifiers that evaluate to themselves. To create a keyword you
+prefix `:` onto an identifier (`:foo` is a keyword, for example). Keywords are
+often used as keys in maps which act like records in other languages. The colon
+at the front is a prefix form of the colon that follows the name of a field in
+other languages. For example, `{name: "foo", age: 22}` in JavaScript becomes
+`{:name "foo" :age 22}` in Radicle.
+
+```radicle
+:foo ;; ==> :foo
+```
+
+## Atoms
+
+Atoms are identifiers which, when evaluated, lookup the value bound to that
+identifier in the current environment:
+
+```radicle
+(def foo 42)
+
+foo ;; ==> 42
+```
+
### Vectors
`radicle`'s *vectors* are an array-like container for values. Literal notation
diff --git a/docs/source/guide/GettingStarted.rst b/docs/source/guide/GettingStarted.rst
deleted file mode 100644
index 6828310..0000000
--- a/docs/source/guide/GettingStarted.rst
+++ /dev/null
@@ -1,49 +0,0 @@
-Getting Started
-==================
-
-The easiest way to play with `radicle` is to use the online REPL, available at
-the `radicle` website_.
-
-.. _website: http://www.radicle.xyz
-
-The online REPL is quite limited, however (and slow). So you will probably also
-want the `radicle` executable.
-
-Building from source
-----------------------
-
-In order to build from source, you'll need stack_:
-
-.. _stack: https://docs.haskellstack.org/en/stable/README/
-
-.. code-block:: bash
-
- curl -sSL https://get.haskellstack.org/ | sh
-
-The centralized server also requires PostgreSQL libs. On Ubuntu, you can
-`apt-get install libpq-dev libtinfo-dev`. On MacOS, you can `brew install postgresql`.
-
-You can then download and build the latest source code for `radicle` from
-http://git.oscoin.io/radicle:
-
-.. code-block:: bash
-
- git clone https://github.com/oscoin/radicle.git
- cd radicle
- stack build
- stack install
-
-You can test that `radicle` was properly installed by running:
-
-.. code-block:: bash
-
- radicle --help
-
-Note that the `radicle` executable always takes a file as an argument. If you
-want to run it interactively (i.e., as a REPL), you'll need to pass it the REPL
-file (included in the repository):
-
-
-.. code-block:: bash
-
- radicle rad/repl.rad
diff --git a/docs/source/guide/Issues.lrad b/docs/source/guide/Issues.lrad
index c24f783..341a1c6 100644
--- a/docs/source/guide/Issues.lrad
+++ b/docs/source/guide/Issues.lrad
@@ -1,4 +1,4 @@
-# Issues machine
+# Issue machine tutorial
## Adding an removing issues
diff --git a/docs/source/guide/index.rst b/docs/source/guide/index.rst
index 8e63a93..affbb11 100644
--- a/docs/source/guide/index.rst
+++ b/docs/source/guide/index.rst
@@ -1,62 +1,19 @@
The radicle guide
==================
-radicle is a language for building and interacting with chains of the Open
-Source Network. What these chains do--how they behave--is entirely up to you.
+radicle is a language for building and interacting with P2P Radicle
+Machines. What these machines do--how they behave--is entirely up to you.
This guide provides an introduction to radicle--as a language, as a tool for
building chains, and as a means of interacting with existing chains.
-
-An example
-------------
-
-As a running example, we'll create a chain for managing the issues of a
-repository. We'll see how to define the format of issues that can be created;
-how to define rights and permissions for certain types of interaction; and
-how to allow for future changes to the chain.
-
-.. code-block:: radicle
-
- (load! (find-module-file! "prelude.rad"))
- (def issues (ref { :open nil :closed nil }))
- (def system (ref {}))
-
- (def new-feature-request
- (fn [author description test-case]
- ...))
-
- (def new-bug-report
- (fn [author description test-case]
- ...))
-
- (def new-question
- (fn [author description]
- ...))
-
- (def close-issue ...)
-
- (def can-modify ...)
-
- (def modify-system ..)
-
- (write-ref system
- { :feature-handler new-feature-request
- :bug-handler new-bug-report
- :question-handler new-question
- :can-modify can-modify
- })
-
-
- (def handle-input
- (fn [expr]
- ...))
-
+Please see the [installation
+instructions](http://radicle.xyz/docs/index.html#installation-setup) to get
+started.
.. toctree::
:maxdepth: 2
- GettingStarted.md
Basics.lrad
Modules.lrad
PatternMatching.lrad
diff --git a/docs/source/index.rst b/docs/source/index.rst
index cb55799..0cefeab 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -3,16 +3,13 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
-radicle
+Radicle
===================================
.. toctree::
:maxdepth: 3
guide/index.rst
- guide/GettingStarted.rst
- guide/Basics.lrad
- guide/DataValidation.rst
guide/Testing.rst
guide/Issues.lrad
reference.rst