+
+
+
diff --git a/gh-pages/common-errors.md b/gh-pages/common-errors.md
new file mode 100644
index 0000000000..27a2b442d4
--- /dev/null
+++ b/gh-pages/common-errors.md
@@ -0,0 +1,200 @@
+---
+layout: default
+title: Common Errors
+---
+
+The following types of programming errors have been identified as frequently occurring among beginning programmers on Stack Overflow:
+
+* [Floating point errors due to binary floating point](#floating_point)
+* [Writing division expressions such as `5 / 2` and not expecting integer division](#integer_division)
+* [Writing `if (x = 0)` when `if (x == 0)` is intended](#assignment_equals)
+* [Null pointer exceptions](#null_pointer)
+* [Unintended empty loop with `while (condition);`](#empty_loop)
+* [Writing `if a == b or c` (in Python) to test whether `a` is equal to either `b` or `c`](#logical_alternative)
+* [Catching all exceptions](#catch_all)
+* [Accidentally shadowing outer scope variables with inner declaration](#shadow_variables)
+* [Returning a reference to a local variable (C++)](#return_reference)
+* [Partial reading of typed user input using Java `Scanner` or C `scanf('%c')`](#partial_input)
+* [Writing `^` to mean exponentiation in C or Java](#exponentiation_xor)
+* [Forgetting to use the return value of a function](#return_value)
+
+
+
+## Floating point errors due to binary floating point
+
+Most languages use [IEEE 754](https://en.wikipedia.org/wiki/IEEE_floating_point) binary floating point for non-integer calculations.
+Although this is well-defined, it is often counterintuitive for beginners. Consider the following Python session:
+
+{% highlight python %}
+>>> a = 0.1
+>>> b = a + a + a
+>>> b
+0.3
+>>> b == 0.3
+False
+{% endhighlight %}
+
+This happens because `0.2` cannot be repesented exactly in binary floating point.
+
+To resolve this problem, Neon uses the [decimal64](https://en.wikipedia.org/wiki/Decimal64_floating-point_format) floating point type, which matches the base 10 that humans use to read and write numbers.
+
+
+
+## Writing division expressions such as `5 / 2` and not expecting integer division
+
+Consider the following C statements:
+
+{% highlight c %}
+int a = 5;
+int b = 2;
+double c = a / b;
+{% endhighlight %}
+
+Beginners rightly assume that `c` will be `2.5` as the result of the division.
+However, the C language definition states that `/` will be *integer* division if both operands are integers.
+So, the result in `c` is `2`.
+
+To resolve this problem, the only number type in Neon is decimal64 floating point (called `Number`).
+In contexts such as array indexing where integers are expected, values are checked for the presence of a fractional part before trying to use them.
+
+
+
+## Writing `if (x = 0)` when `if (x == 0)` is intended
+
+In C and derived languages, `x = 0` is an *expression* with the result 0.
+Some compilers raise a warning if an expression like `(x = 0)` is used in a conditional statement, as it is not likely to be what is intended.
+However, this is not prohibited by the language.
+
+To resolve this problem, the assignment operator in Neon is `:=` and assignment cannot appear within an expression.
+
+
+
+## Null pointer exceptions
+
+In many common systems languages (eg. C, C++, Java, C#), a pointer may hold a "null" value which is a runtime error to dereference. Tony Hoare has called the introduction of the null reference in ALGOL his ["billion-dollar mistake"](https://en.wikipedia.org/wiki/Tony_Hoare).
+
+To resolve this problem, Neon introduces the idea of a "valid" pointer. A valid pointer is one that has been checked against `NIL` (the null reference) using a special form of the `IF` statement. The resulting valid pointer can be dereferenced without causing a null pointer exception.
+
+ TYPE Node IS RECORD
+ next: POINTER TO Node
+ value: String
+ END RECORD
+
+ VAR node: POINTER TO Node := NIL
+
+ IF VALID node AS p THEN
+ print(p->value)
+ END IF
+
+
+
+## Unintended empty loop with `while (condition);`
+
+In C and derived languages, sometimes a loop or conditional is mistakenly written as:
+
+{% highlight c %}
+while (x < 5);
+{
+ printf("%d\n", x);
+}
+{% endhighlight %}
+
+The trailing `;` on the `while` statement is in fact an empty loop body and the loop is an infinite loop.
+
+To resolve this problem, Neon requires an explicitly terminated block in every compound statement:
+
+ VAR x: Number := 0
+
+ WHILE x < 5 DO
+ print(x.toString())
+ INC x
+ END WHILE
+
+
+
+## Writing `if a == b or c` (in Python) to test whether `a` is equal to either `b` or `c`
+
+In Python, beginners find it natural to write code like:
+
+{% highlight python %}
+if name == "Jack" or "Jill":
+ ...
+{% endhighlight %}
+
+This is valid because the `"Jill"` is automatically treated as a boolean expression (with value `True`) and combined with the `name == "Jack"` condition using the `or` operator.
+
+To resolve this problem, values in Neon cannot be automatically converted from one type to another (in particular, not to Boolean).
+
+
+
+## Catching all exceptions
+
+Languages with complex exception hierarchies (eg. C++, Java, C#, Python) allow the program to catch *all* types of exceptions using a construct such as `catch (...)` (C++) or `except:` (Python).
+This generally has the unintended effect of masking exceptions that may not be among those expected by the programmer.
+
+Neon does not have an exception hierarchy, and the exception handling always uses explicitly named exceptions (there is no way to catch *all* types of exceptions).
+
+
+
+## Accidentally shadowing outer scope variables with inner declaration
+
+Most programming languages allow names declared in a nested scope to *shadow* names declared in an enclosing scope (such as the global scope). For example, in C:
+
+{% highlight c %}
+int x;
+
+void f() {
+ int x;
+ x = 5;
+}
+{% endhighlight %}
+
+This can lead to confusion due to unexpectedly using the wrong variable.
+
+In Neon, it is an error for a declaration to shadow an outer declaration.
+
+
+
+## Returning a reference to a local variable (C++)
+
+In C++, it is possible to return a reference (or pointer) to a local variable:
+
+{% highlight c++ %}
+int &foo(int x) {
+ int a = x * x;
+ return a;
+}
+{% endhighlight %}
+
+This is *undefined behaviour* because the reference returns to memory that has been deallocated as soon as the function returns.
+
+This is resolved in Neon by not having references.
+
+
+
+## Partial reading of typed user input using Java `Scanner` or C `scanf('%c')`
+
+The Java `Scanner` class and C `scanf` functions treat their input as a stream.
+However, when used with interactive terminal input, they do not return a value until an *entire* line has been typed at the console.
+This causes confusion when the user types more than what is expected and the remainder of what the user typed is held in the input buffer until the next time input is requested.
+At that time, the contents of the buffer are used without waiting for user input.
+
+This is resolved in Neon by only providing line oriented input for text in traditional tty mode, or single character input via curses.
+
+
+
+## Writing `^` to mean exponentiation in C or Java
+
+Sometimes beginners expect the `^` operator to mean exponentiation (eg. `dist = sqrt(a^2 + b^2)`).
+However, `^` means bitwise XOR in many languages, which is not expected.
+
+In Neon, `^` means exponentiation.
+
+
+
+## Forgetting to use the return value of a function
+
+Many programming languages permit a function that returns a value to be called without actually using the return value.
+This is a frequent source of bugs because the return value may indicate an error condition, which is then ignored.
+
+In Neon, it is an error to call a function that returns a value without using that value in some way.
diff --git a/gh-pages/css/screen.css b/gh-pages/css/screen.css
new file mode 100644
index 0000000000..19ef18b05a
--- /dev/null
+++ b/gh-pages/css/screen.css
@@ -0,0 +1,30 @@
+body {
+ background-color: white;
+ font-family: Georgia, "Liberation Serif", serif;
+}
+
+#page {
+ max-width: 780px;
+ text-align: left;
+ margin: 2.5em auto 2em;
+}
+
+#page .title {
+ text-align: center;
+ font-size: 300%;
+ font-family: sans-serif;
+ text-shadow: 0 0 0.5em red;
+}
+
+#page .title a {
+ text-decoration: none;
+}
+
+#page .links {
+ text-align: center;
+}
+
+pre {
+ padding: 1em 2em 1em 2em;
+ background-color: #eeeeee;
+}
diff --git a/gh-pages/docs.md b/gh-pages/docs.md
new file mode 100644
index 0000000000..f567bc8597
--- /dev/null
+++ b/gh-pages/docs.md
@@ -0,0 +1,14 @@
+---
+layout: default
+title: Neon Programming Language Documentation
+---
+
+The Neon documentation is split into several parts.
+
+* [**Manifesto**](manifesto.html). Why does Neon exist? What problems does it try to solve?
+* [**Tutorial**](tutorial.html). This is an introduction to the Neon language.
+* [**Standard Library**](/html/). This describes every module in the Neon Standard Library.
+* [**Overview for Experts**](overview.html). This is a very quick overview of the language for experienced programmers.
+* [**Language Reference**](reference.html). This is a detailed reference describing every language feature.
+* [**Grammar Diagrams**](grammar.xhtml). Detail of the language grammar using "railroad diagrams".
+* [**Samples**](/samples/). This describes a number of sample programs written in Neon.
diff --git a/gh-pages/download.md b/gh-pages/download.md
new file mode 100644
index 0000000000..69eae52766
--- /dev/null
+++ b/gh-pages/download.md
@@ -0,0 +1,7 @@
+---
+layout: default
+title: Download
+---
+
+There are no pre-built packages available yet.
+However, you can download a [zip file of the current source tree](https://github.com/ghewgill/neon-lang/archive/master.zip) from GitHub.
diff --git a/gh-pages/grammar.xhtml b/gh-pages/grammar.xhtml
new file mode 100644
index 0000000000..c54090eafc
--- /dev/null
+++ b/gh-pages/grammar.xhtml
@@ -0,0 +1,4448 @@
+
+
+
+
+
+
+
+
+ Neon
+
+
+
+
+ {{ content }}
+ + home | + documentation | + download | + source +
+
diff --git a/gh-pages/manifesto.md b/gh-pages/manifesto.md
new file mode 100644
index 0000000000..bcd81a40d0
--- /dev/null
+++ b/gh-pages/manifesto.md
@@ -0,0 +1,46 @@
+---
+layout: default
+title: Neon Manifesto
+---
+
+Programming languages today are full of features, and there is a trend toward brevity.
+Brevity is highly expressive, for an expert who understands the notation.
+However, for a new learner or a casual user, brevity promotes unreadable code.
+
+## Principles of Design
+
+* Prefer keywords over punctuation
+* Good error messages
+* Avoid implicit behaviour
+* Explicit declarations
+* Single meaning per keyword/operator
+* Principle of least surprise
+* Easy lookup
+
+### Prefer keywords over punctuation
+
+Punctuation is important, but it should be used sparingly.
+
+### Good error messages
+
+Error messages should explain what is wrong, with suggestions of ways to correct the problem.
+
+### Avoid implicit behaviour
+
+There will be no hidden, implicit, or automatic calls made to code that is not expressly visible in the source.
+
+### Explicit declarations
+
+Everything is declared, and identifiers from modules are always qualified.
+
+### Single meaning per keyword/operator
+
+To the greatest reasonable extent, keywords and operators only have one meaning.
+
+### Principle of least surprise
+
+This one is hard to quantify, but it's good.
+
+### Easy lookup
+
+By using keywords instead of punctuation, and by using explicit declarations, it is easy to look up unknown things in the documentation.
diff --git a/gh-pages/motivation.md b/gh-pages/motivation.md
new file mode 100644
index 0000000000..ddb7db00ac
--- /dev/null
+++ b/gh-pages/motivation.md
@@ -0,0 +1,32 @@
+---
+layout: default
+title: Motivation
+---
+
+The primary goal of Neon is to find out whether a useful programming language can avoid some of the common errors that beginners frequently encounter in other languages.
+
+After many years of participation on [Stack Overflow](http://stackoverflow.com), one starts to recognise the same kinds of problems that beginners encounter over and over.
+Some of these errors are:
+
+* Floating point errors due to binary floating point
+* Writing `if (x = 0)` when `if (x == 0)` is intended
+* Null pointer exceptions
+* Unintended empty loop with `while (condition);`
+* Forgetting to use the return value of a function
+
+It is my opinion that these kinds of errors can be avoided by language design.
+Neon is an experiment that attempts to show that this is the case.
+
+## Influences
+
+Many languages have influenced the design or specific features of Neon. Some are:
+
+- Pascal (`:=` for assignment, `VAR` keyword, nested functions)
+- Modula-2 (upper case keywords)
+- Ada (`IN`, `OUT`, `INOUT` parameter passing modes, arbitrary base notation)
+- Python (standard library)
+- C++ (`<...>` syntax for parameterised types)
+- Prolog (`%` single line comment character)
+- Scheme (`%|...|%` block comment, Scheme uses `#|...|#`)
+
+There is also a lot of *negative* influence, where the presence of a feature in a language has the potential to be misused (eg. `if (a = b)` in C).
diff --git a/gh-pages/overview.md b/gh-pages/overview.md
new file mode 100644
index 0000000000..5b64aa322e
--- /dev/null
+++ b/gh-pages/overview.md
@@ -0,0 +1,241 @@
+---
+layout: default
+title: Neon Overview
+---
+
+# Neon Overview
+
+The following is a brief description of Neon for experienced programmers.
+There are plenty of examples, because experienced programmers know how to read code, and can pick up concepts more quickly by reading code than by reading a description of code.
+
+Neon is a statically typed imperative language, with roots in Pascal, Modula-2, Ada, and [others](motivation.html).
+Program structure and modules are influenced by Python.
+
+ % This sample program greets the user
+ % until an empty line is entered.
+
+ LOOP
+ LET name: String := input("What is your name? ")
+ IF name = "" THEN
+ EXIT LOOP
+ END IF
+ print("Hello, \(name).")
+ END LOOP
+
+## General
+
+All identifiers are case sensitive.
+Language defined keywords are all upper case.
+Semicolons are not used.
+Identifier scope is defined by program block structure.
+Assignments have value semantics (deep copy).
+Forward declarations are not required.
+All variables must be explicitly initialised before use.
+
+## Types
+
+The scalar types are `Boolean` (`TRUE` or `FALSE`), `Number` (decimal floating point), `String` (Unicode text), `Bytes` (arbitrary blocks of bytes), and enumerations.
+Aggregate types are `RECORD` (named fields), `Array` (arbitrary size vector), and `Dictionary` (map indexed by a `String` key).
+Dynamic heap allocation is supported by a `POINTER` type.
+
+ TYPE Colour IS ENUM
+ red
+ green
+ blue
+ END ENUM
+
+ TYPE Person IS RECORD
+ name: String
+ eyes: Colour
+ END RECORD
+
+ LET b: Boolean := TRUE
+ LET n: Number := 123.456
+ LET s: String := "Hello world"
+ LET y: Bytes := HEXBYTES "00 01 02 03"
+ LET e: Colour := Colour.green
+ LET r: Person := Person("Alice", Colour.green)
+ LET a: Array-
+
- Lexical Structure
+
-
+
- Comments +
- Keywords +
- Identifiers +
- Numbers +
- Strings +
+ - Types
+
-
+
- Boolean +
- Number +
- String +
- Bytes +
- Enumeration +
- Record +
- Array +
- Dictionary +
- Pointer +
+ - Expressions + +
- Statements + +
- Functions
+
-
+
- Parameter Modes +
- Default Parameter Value +
- Named Parameters +
- External Functions +
+ - Modules
+
-
+
- Export +
- Import +
- Module Path +
+ - Standard Library + +
- Grammar +
-
+
- Same directory as the importing source file +
- The current directory +
- The directories in the environment variable NEONPATH +
- The directories listed in the .neonpath file in the current directory +