Documentation changes for v0.7.0

1 files changed, 36 insertions, 99 deletions

diff --git a/README.md b/README.md
index 1c59376f4..f9f756202 100644
--- a/README.md
+++ b/README.md
@@ -1,24 +1,24 @@
 [![Gitter](https://badges.gitter.im/LuxProgrammingLanguage/community.svg)](https://gitter.im/LuxProgrammingLanguage/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
 
-## What is Lux?
+# What is Lux?
 
 Lux is a new programming language in the making.
 
 It's meant to be a functional, statically-typed Lisp that will run on several platforms, such as the Java Virtual Machine and JavaScript, Python, Lua, or Ruby interpreters.
 
-### What's the current version?
+## What's the current version?
 
-0.6.4
+0.7.0
 
-### How far ahead is the project?
+## How far ahead is the project?
 
 Lux is in the **beta** stage.
 
 The JVM compiler is pretty stable and the standard library has grown to a respectable size.
 
-Also, new experimental support for JavaScript, Python, Lua, and Ruby has been added.
+Also, support for JavaScript, Python, Lua, and Ruby has been added.
 
-### What's the license?
+## What's the license?
 
 [Custom License](license.txt)
 
@@ -34,54 +34,49 @@ You can become a patron by supporting Lux through [Patreon](https://www.patreon.
 
 The language is mostly inspired by the following 3 languages:
 
-* Clojure (syntax, overall look & feel)
+* Clojure (syntax)
 * Haskell (functional programming)
-* Standard ML (module system)
+* Standard ML (polymorphism)
 
-### Types
-
-They are implemented as plain-old data-structures whose expressions get eval'ed by the compiler and integrated into the type-checker.
-
-That means it's actually possible to generate types via functions and macros.
-
-### Module system
+### Concurrency
 
-The module system is heavily inspired by Standard ML.
+Lux supports multiple paradigms for concurrent programming:
 
-The main difference between Lux and Standard ML is that Standard ML separates interfaces/signatures and implementations/structures from the rest of the language, whereas Lux implements them on top of the base language.
+* Threads and atomic references.
+* Asynchronous programming (i.e. promises & futures).
+* Functional Reactive Programming (FRP).
+* Software-Transactional Memory (STM).
+* The actor model.
 
-How?
+More paradigms will be supported in the future.
 
-By implementing interfaces/signatures as record-types and implementations/structures as actual records.
+### Multi-platform
 
-##### But, why not just use type-classes?
+Lux can compile to JVM bytecode, and thereby it can run anywhere Java can.
 
-Haskell's type-class system forces the user to only specify 1 instance for any given type-class and its argument.
+On top of that, Lux can compile to JavaScript code, Python, Ruby, and Lua.
 
-If there are more than 1 possible valid instances (as is the case for Monoid of Int), you have to resort to _newtype hacks_ to be able to provide alternative implementations.
+This makes Lux an extremely versatile language.
 
-By using a system like Standard ML's, that problem is averted.
+And more platforms are coming in the future!
 
-Additionally, by hosting the module system on top of records, which are regular values, you get the further benefit that structures can be parameterized at run-time just like any other value.
+**Note**: Lux code can also be compiled into libraries that can be consumed in any of the platforms Lux can compile to; which means Lux makes for amazing glue code for polyglot projects.
 
-You can also write functions that take and return structures (as _functors_ do in Standard ML), and you can generate structures on the fly.
+### Extensibility
 
-> Also, Lux now offers a mechanism for easy polymorphism, just like Haskell's type-classes, but built upon its module system, thanks to the `library/lux/type/auto` module and its `##` macro.
+Lux is being built to be the most extensible and versatile language ever made.
 
-> You can learn more about that by reading the book and the documentation.
+Not only can its syntax be extended through macros, but even the semantics of the language, its available roster of optimizations, and even its mechanisms for code-generation can be extended with a mechanism for compiler extension which is similar to its mechanism for macro definition.
 
-### Functional programming
+A new (experimental) meta-compiler architecture has been added which will enable Lux to become on its own a platform for polyglot programming and language experimentation.
 
-While the means to do Java-interop are provided, Lux is commited to functional programming.
+### Types
 
-Functions are curried and partial application is as simple as just applying a function to less arguments than it needs (as in Haskell).
+They are implemented as plain-old data-structures whose expressions get eval'ed by the compiler and integrated into the type-checker.
 
-e.g.
+That means it's actually possible to generate types via functions and macros.
 
-```
-... Add 1 to each number in the list.
-(each (+ 1) (list 1 2 3 4 5))
-```
+They can also be accessed from within macros to generate all sorts of type-driven code.
 
 ### Macros
 
@@ -89,69 +84,11 @@ Unlike in most other lisps, Lux macros are monadic.
 
 The `(Meta a)` type is the one responsible for the magic by threading `Lux` compiler-state instances through macros.
 
-You can use `macro:` to define these monadic macros.
-
-Alternatively, you can use the `syntax:` macro, which also offers monadic parsing of Code tokens for convenience.
-
-### Custom pattern-matching
-
-##### Wait... wut?
-
-Custom pattern-matching basically means that you can use macros to provide custom syntax and features on top of the pattern-matching macro `case`.
-
-For instance, the `list` and `list&` macros are used to build lists.
-
-But you can also use them to destructure lists inside pattern-matching:
-
-```
-... Try to pattern-match against a list, extract its elements and multiply them.
-(: (Maybe Nat)
-   (case (: (List Nat)
-            (list 2 3))
-     {#Item x {#Item y {#End}}}
-     {#Some (* x y)}
-
-     _
-     {#None}))
-
-(: (Maybe Nat)
-   (case (: (List Nat)
-            (list 2 3))
-     (^ (list x y))
-     {#Some (* x y)}
-   
-     _
-     {#None}))
-```
-
-There is also the special **^or** macro, which introduces *or patterns*:
-
-```
-(type: Weekday
-  (Variant
-    {#Monday}
-    {#Tuesday}
-    {#Wednesday}
-    {#Thursday}
-    {#Friday}
-    {#Saturday}
-    {#Sunday})))
-
-... Returns TRUE if it's either Saturday OR Sunday.
-(def (weekend? day)
-  (-> Weekday Bit)
-  (case day
-    (^or {#Saturday}
-         {#Sunday})
-    true
-
-    _
-    false))
-```
+You can use `macro` to define these monadic macros.
 
-> Please note that `^` and `^or` are just macros like any other and anyone can implement them.
+Alternatively, you can use the `syntax` macro, which also offers monadic parsing of `Code` tokens for convenience.
 
-### Is there a community for this?
+## Is there a community for this?
 
 Say hi at Gitter: https://gitter.im/LuxProgrammingLanguage/community
 
@@ -159,11 +96,11 @@ Come join the forum: http://luxlang.freeforums.net/
 
 If you want to communicate with me directly, just email: luxlisp@gmail.com
 
-### How can I edit Lux code?
+## How can I edit Lux code?
 
 Check out the Emacs plugin for it: https://github.com/LuxLang/lux/tree/master/lux-mode
 
-### Where do I learn Lux?
+## Where do I learn Lux?
 
 The main resource is [the book](documentation/book/the_lux_programming_language/index.md).
 
@@ -171,7 +108,7 @@ It will always be up-to-date with the latest stable version of the language.
 
 Also, you can check out [the documentation for the currently available modules](documentation/library/standard/jvm.md).
 
-### How can I contribute?
+## How can I contribute?
 
 For starters, you can check out the [Trello board](https://trello.com/b/VRQhvXjs/lux-jvm-compiler) for Lux development.