Tidying up a bit (#143)

* Consolidate READMEs, remove some references to backends

* Update default gist ID

This one uses `gist.github.com` links for the examples so that the links
work.

* adjust heading levels

* Update link pointing to gh-pages branch

We probably won't be using this branch once we deploy the current
version, and everything is in the main repo README now anyway.

* Update README.md

Co-Authored-By: Thomas Honeyman <[email protected]>

* Update README.md

Co-Authored-By: Thomas Honeyman <[email protected]>

* Mention defaults with query string parameters

* Reword 200 response status rationale

Co-authored-by: Thomas Honeyman <[email protected]>

Author: hdgarrood

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2013-16 PureScript
+Copyright (c) 2013-20 PureScript
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

README.md

@@ -1,44 +1,50 @@
-# PureScript API
+# Try PureScript
 
 [![Build Status](https://api.travis-ci.org/purescript/trypurescript.svg?branch=master)](http://travis-ci.org/purescript/trypurescript)
 
-Very basic web service which wraps the PureScript compiler.
+[Try PureScript](https://try.purescript.org) is an online PureScript code editor for quickly experimenting with PureScript code snippets and ideas. It consists of a client and a server component, both of which live within this repository.
 
-[Client code](https://github.com/purescript/trypurescript/tree/gh-pages)
+## Features:
 
-## API
+- Writing code using the [Ace Editor](http://ace.c9.io)
+- Automatic compilation
+- PureScript syntax highlighting
+- Run and print output or show resulting JavaScript
+- Multiple view modes: code, output or both
+- Persistent session
+- Load PureScript code from Github Gists
 
-### Compile PureScript code
-
-**POST /compile**
-
-- Request body: PureScript code
-- Response body: Either `{ js: "..." }` or `{ error: "..." }`
-- Status code: 200 (success)
+### Control Features via the Query String
 
-The response does not use error codes, to make it easier to use the API from another domain using CORS.
+Most of these features can be controlled not only from the toolbar, but also using the [query parameters](https://en.wikipedia.org/wiki/Query_string):
 
-The output code will contain references to preloaded modules using `require` calls. To run these files in the browser, it is necessary to either use a `require` shim (such as require1k), or replace these calls and deploy a bundle of precompiled modules (the Try PureScript client uses the second approach).
+- **Load From Gist**: Load PureScript code from Gist id using the `gist` parameter
+    - Example: `gist=37c3c97f47a43f20c548` will load the code from this Gist if the file was named `Main.purs`
 
-## Configuration
+- **View Mode**: Control the view mode using the `view` parameter
+    - Options are: `code`, `output`, `both` (default)
+    - Example: `view=output` will only display the output
 
-The application takes the following arguments on the command line:
+- **Auto Compile**: Automatic compilation can be turned off using the `compile` parameter
+    - Options are: `true` (default), `false`
+    - Example: `compile=false` will turn auto compilation off
 
-- port number
-- a list of input source files
+- **JavaScript Code Generation**: Print the resulting JavaScript code in the output window instead of the output of the program using the `js` parameter
+    - Options are: `true`, `false` (default)
+    - Example: `js=true` will print JavaScript code instead of the program's output
 
-### Example
+- **Session**: Load code from a session which is stored with [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) using the `session` parameter
+    - Usually managed by Try PureScript
+    - Example: `session=9162f098-070f-4053-60ea-eba47021450d` (Note: will probably not work for you)
+    - When used with the `gist` query parameter the code will be loaded from the Gist and not the session
 
-    dist/build/trypurescript/trypurescript 8081 'bower_components/purescript-*/src/**/*.purs'
-    
-# Development
+## Development
 
-## 1. Client setup
+### 1. Client setup
 
-```
+```sh
 git clone [email protected]:purescript/trypurescript.git
-cd trypurescript
-git co gh-pages
+cd trypurescript/client
 
 bower install
 npm install
@@ -49,32 +55,50 @@ httpserver 8080 #eg with: alias httpserver='python -m SimpleHTTPServer'
 open http://localhost:8080
 ```
 
-## 2. Work with local compile server
+### 2. Local compile server setup
 
-```
+```sh
 git clone [email protected]:purescript/trypurescript.git
 cd trypurescript
 
 stack build
 
-# use one of the backends
-cd staging/core
-# get the sources of the deps
+# Install PureScript dependencies
+cd staging
 psc-package install
 
 # note: globs like **/src/** do not work
-stack exec trypurescript 8081 ".psc-package/psc-0.13.6/*/*/src/**/*.purs" "src/*.purs"
+stack exec trypurescript 8081 ".psc-package/psc-0.13.6-*/*/*/src/**/*.purs" "src/*.purs"
 # should output that is is compiling the sources (first time)
 # then: Setting phasers to stun... (port 8081) (ctrl-c to quit)
 ```
 
-## 3. Point client to local compile server
+## Server API
 
-(instead of the ones at try.purescript.org)
-```
-# edit API.purs
+The server is a very basic web service which wraps the PureScript compiler, allowing clients to send PureScript code to be compiled and receiving either compiled JS or error messages in response.
 
-  , compile: compile "http://localhost:8081"
-  , getBundle: getDefaultBundle "http://localhost:8081"
+### Compile PureScript code
 
-```
+**POST /compile**
+
+- Request body: PureScript code
+- Response body: Either `{ js: "..." }` or `{ error: "..." }`
+- Status code: 200 (success)
+
+Note that if the code in the request body fails to compile, this is considered a success from the perspective of the API, so compilation failures will be returned with 2xx status codes.
+Among other things, this makes it easier to use the API from another domain using CORS.
+
+The output code will contain references to preloaded modules using `require` calls.
+To run these files in the browser, it is necessary to either use a `require` shim (such as require1k), or replace these calls and deploy a bundle of precompiled modules.
+The Try PureScript client uses the second approach.
+
+### Configuration
+
+The server application takes the following arguments on the command line:
+
+- port number
+- a list of input source files
+
+#### Example
+
+    dist/build/trypurescript/trypurescript 8081 'bower_components/purescript-*/src/**/*.purs'

client/README.md

@@ -63,7 +63,7 @@
           <input id="showjs" name="showjs" title="Show resulting JavaScript code instead of output" value="showjs" type="checkbox">
           <label id="showjs_label" for="showjs" title="Show resulting JavaScript code instead of output">Show JS</label>
         </li><li class="menu-item">
-          <a id="helplink" href="https://github.com/purescript/trypurescript/tree/gh-pages/README.md" target="trypurs_readme">
+          <a id="helplink" href="https://github.com/purescript/trypurescript/README.md" target="trypurs_readme">
             <label id="help" title="Learn more about Try PureScript">Help</label>
           </a>
         </li>

client/index.html

@@ -7,4 +7,4 @@ compileUrl :: String
 compileUrl = "http://localhost:8081"
 
 mainGist :: String
-mainGist = "e1d317102aad40207309d8873e301273"
+mainGist = "7ad2b2eef11ac7dcfd14aa1585dd8f69"