Merge pull request #218 from phel-lang/documentation-v0.1.0

Documentation v0.1.0

Changelog.md

@@ -0,0 +1,5 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+## 0.1.0 (2020-31-01)
+Initial release

doc/content/_index.md

@@ -54,4 +54,4 @@ Phel requires PHP 7.4 or higher and Composer. Read the [Getting Started Guide](/
 
 ## Status of Development
 
-Phel has not been released yet, but it is fairly complete. In the next weeks or months I will probably find some more edge cases that I will fix before the first official release. Maybe some of you are willing to test it out and give feedback.
+Phel has is fairly complete but not marked as ready. We still want to envolve this language without thinking to much about breaking changes. Maybe some of you are willing to test it out and give feedback.

doc/content/documentation/getting-started.md

@@ -18,17 +18,17 @@ cd hello-world
 composer init
 ```
 
-Composer will ask a bunch of questions that can be answered as in the following example. Make sure to set *Minimum Stability* to **dev**:
+Composer will ask a bunch of questions that can be answered as in the following example.
 
 ```
 Welcome to the Composer config generator
 
 This command will guide you through creating your composer.json config.
 
-Package name (<vendor>/<name>) [jens/phel]: phel/hello-world
+Package name (<vendor>/<name>): phel-lang/hello-world
 Description []:
 Author [Your Name <your.name@domain.com>, n to skip]:
-Minimum Stability []: dev
+Minimum Stability []:
 Package Type (e.g. library, project, metapackage, composer-plugin) []: project
 License []:
 
@@ -38,15 +38,14 @@ Would you like to define your dependencies (require) interactively [yes]? no
 Would you like to define your dev dependencies (require-dev) interactively [yes]? no
 
 {
-    "name": "phel/hello-world",
+    "name": "phel-lang/hello-world",
     "type": "project",
     "authors": [
         {
             "name": "Your Name",
             "email": "your.name@domain.com"
         }
     ],
-    "minimum-stability": "dev",
     "require": {}
 }
 
@@ -57,7 +56,7 @@ Next, require Phel as a dependency.
 
 ```bash
 # Require and install Phel
-composer require phel-lang/phel-lang:dev-master
+composer require phel-lang/phel-lang
 ```
 
 Then, create a new directory `src` with a file `boot.phel` inside this directory.
@@ -87,13 +86,13 @@ For Phel to automatically resolve the project namespace and path, this code need
 }
 ```
 
-> Read documentation for [Configuration](/documentation/configuration) to see all available configuration options for Phel.
+> Read the documentation for [Configuration](/documentation/configuration) to see all available configuration options for Phel.
 
 The final `composer.json` file should look like this:
 
 ```json
 {
-    "name": "phel/hello-world",
+    "name": "phel-lang/hello-world",
     "type": "project",
     "authors": [
         {
@@ -102,16 +101,15 @@ The final `composer.json` file should look like this:
         }
     ],
     "require": {
-        "phel-lang/phel-lang": "dev-master"
+        "phel-lang/phel-lang": "^0.1"
     },
     "extra": {
         "phel": {
             "loader": {
                 "hello-world\\": "src/"
             }
         }
-    },
-    "minimum-stability": "dev"
+    }
 }
 ```
 
@@ -173,6 +171,11 @@ In the browser, the URL `http://localhost:8000` will now print "Hello, World!".
 
 To try Phel you can run a REPL by executing the `./vendor/bin/phel repl` command.
 
+> Read more about the [REPL](/documentation/repl) in its own chapter.
+
+## Phel Scaffolding
+
+As an alternative to the Getting started guide above the [Scaffolding project on Github](https://github.com/phel-lang/phel-scaffolding) is another good starting point.
 
 ## Editor support
 

doc/content/documentation/repl.md

@@ -3,53 +3,64 @@ title = "REPL"
 weight = 18
 +++
 
-Phel provides a interactive prompt where you can type Phel expressions and see the results. This interactive prompt is called REPL (stands for Read-eval-print loop). A REPL is very helpful to test out small task or to play around with the language its self.
+Phel comes with an interactive prompt. The prompt accepts Phel expressions and directly returns the result. This interactive prompt is called REPL (stands for Read-eval-print loop). A REPL is very helpful to test out small tasks or to play around with the language itself.
 
-The REPL can be started with the following command:
+The REPL is started with the following command:
 ```bash
 ./vendor/bin/phel repl
 ```
 
-Afterwards you can type an expression and see the result intermediately
+Afterwards any Phel expression can be typed in.
 
 ```bash
 Welcome to the Phel Repl
 Type "exit" or press Ctrl-D to exit.
->>> (* 6 7)
+phel:1> (* 6 7)
 42
->>>
+phel:2>
+```
+
+The prompt also accepts multiline expressions:
+```bash
+Welcome to the Phel Repl
+Type "exit" or press Ctrl-D to exit.
+phel:1> (+
+....:2>  3
+....:3>  7)
+10
+phel:4>
 ```
 
 Press `Ctrl-D` or type "exit" to end the REPL session.
 
 ## Little helpers
 
-The REPL itsself provides a few little helpers to make you life easier.
+The REPL itself provides a few little helper functions.
 
-The `doc` function returns the documentation for any definition in your scope:
+The `doc` function returns the documentation for any definition in the current scope:
 ```bash
->>> (doc all?)
+phel:1> (doc all?)
 (all? pred xs)
 
 Returns true if `(pred x)` is logical true for every `x` in `xs`, else false.
 nil
->>>
+phel:2>
 ```
 
-The `require` function can be used to require another namespace into the repl. The arguments are the same as the `:require` statement in the `ns` function.
+The `require` function can be used to require another namespace into the REPL. The arguments are the same as the `:require` statement in the `ns` function.
 ```bash
->>> (require phel\html :as h)
+phel:1> (require phel\html :as h)
 phel\html
->>> (h/html [:span])
+phel:2> (h/html [:span])
 <span></span>
->>>
+phel:3>
 ```
 
 The `use` function can be used to add a alias for a PHP class. The arguments are the same as the `:use` statement in the `ns` function.
 ```bash
->>> (use \Phel\Lang\Symbol :as PhelSymbol)
+phel:1> (use \Phel\Lang\Symbol :as PhelSymbol)
 \Phel\Lang\Symbol
->>> (php/:: PhelSymbol (create "foo"))
+phel:2> (php/:: PhelSymbol (create "foo"))
 foo
->>>
+phel:3>
 ```

doc/sass/_base.scss

@@ -49,4 +49,11 @@ textarea,
 [tabindex] {
   -ms-touch-action: manipulation;
   touch-action: manipulation;
-}
+}
+
+blockquote {
+  background: $color-background-light;
+  margin: 0;
+  margin-top: 1.5em;
+  padding: 0.5em 1.5em;
+}