More docs

src/SUMMARY.md

@@ -2,6 +2,26 @@
 
 [Introduction](introduction.md)
 
+# Tutorial
+- [Installation](installation.md)
+  - [Prebuilt Binaries](prebuilt_binaries.md)
+  - [Build dependencies](build_dependencies.md)
+  - [Automated Build Script](automated_build_script.md)
+  - [Building Manually](building_manually.md)
+- [Command Usage](command_usage.md)
+- [Basics](basics.md)
+  - [Hello, World!](hello_world.md)
+  - [Variables](tutorial_variables.md)
+  - [Comments](tutorial_comments.md)
+  - [Values and Types](values_and_types.md)
+- [Functions](functions.md)
+- [Structures](structures.md)
+
+# Guidelines
+- [Naming Conventions](naming_conventions.md)
+- [Comment Conventions](comment_conventions.md)
+- [Code Layout](code_layout.md)
+
 # Specification
 - [Reserved Words](reserved_words.md)
 - [Comments](comments.md)
@@ -12,3 +32,8 @@
 - [Operators](operators.md)
 - [Function Definition](function_definition.md)
 - [Struct Definition](struct_definition.md)
+
+# Release History
+- ["Vela" 0.x.x](vela.md)
+  - [0.1.0](vela_0.1.0.md)
+- ["Fornax" 1.x.x](fornax.md)

src/automated_build_script.md

@@ -0,0 +1,30 @@
+# Automated Build Script
+
+This method requires the following installed:
+
+* uthash (in `/usr/include` or similar)
+* A gcc-compatible C compiler linked to `cc`
+  * GCC and Clang are both tested and will yield similar results.
+* Git (to get source code)
+* Make (to organise building the code)
+
+Refer to [Build Dependencies](build_dependencies.md) for instructions on how to install dependencies.
+
+## Running the installer
+
+Run this command in your terminal:
+
+```sh
+bash -c "$(curl -fsSL https://sols.dev/install.sh)"
+```
+
+This will:
+
+* Download a shell script from `https://sols.dev/install.sh`
+* Run the contents of the shell script in the `bash` command interpreter
+
+The script does the following:
+
+* Checks if Ground and Solstice are installed on your system.
+* If either Ground or Solstice aren't avaliable, it will download, build, and install the source code.
+* If Ground or Solstice are installed, it will update them to the latest version.

src/basics.md

@@ -0,0 +1,3 @@
+# Basics
+
+This part of the tutorial shows you the basics of using Solstice. Click next to see the "Hello, World!" program!

src/build_dependencies.md

@@ -0,0 +1,25 @@
+# Build dependencies
+
+## macOS
+
+```sh
+xcode-select --install
+```
+
+Then, download UTHash [here](https://github.com/troydhanson/uthash/archive/master.zip), and copy the contents of the `include` folder to `/usr/local/include`:
+
+```sh
+sudo cp (/path/to/uthash-master)/include/* /usr/local/include
+```
+
+## Ubuntu/Debian
+
+```sh
+sudo apt install gcc git make uthash-dev
+```
+
+## Arch Linux
+
+```sh
+sudo pacman -S --needed gcc git make uthash
+```

src/building_manually.md

@@ -0,0 +1,23 @@
+# Building Manually
+
+Refer to [Build Dependencies](build_dependencies.md) for instructions on how to install dependencies.
+
+Build and install Ground:
+
+```sh
+git clone https://chookspace.com/ground/ground
+cd ground
+make
+sudo make install
+cd ..
+```
+
+After this, build and install Solstice:
+
+```sh
+git clone https://chookspace.com/solstice/solstice
+cd solstice
+make
+sudo make install
+cd ..
+```

src/code_layout.md

@@ -0,0 +1 @@
+# Code Layout

src/command_usage.md

@@ -0,0 +1,51 @@
+# Command Usage
+
+```
+Solstice programming language
+Usage: solstice <file> [-h] [--help] [-p] [--print] [-b <file>] [--bytecode <file>] [-c <file>] [--compile <file>]
+Args:
+  <file>:                         Solstice source file
+  -h or --help:                   Prints this help message and exits
+  -p or --print:                  Prints textual version of Ground bytecode to console
+  -b <file> or --bytecode <file>: Generates Ground bytecode (.grbc) and saves it to the provided filename
+  -c <file> or --compile <file>:  Compiles Ground to Linux x86_64 assembly, outputs a binary to the provided filename (experimental)
+  If no extra arguments are provided, the generated Ground bytecode will be executed.
+```
+
+## Arguments:
+
+### `<file>`
+
+The Solstice source file to run.
+
+There should never be more than one file, as Solstice allows files to import each other, rather than compiling multiple files into one manually.
+
+### `-h` or `--help`
+
+Shows the help message above.
+
+### `-p` or `--print`
+
+Prints the textual version of the generated Ground bytecode to the console.
+
+This is useful for debugging the compiler, and ensuring the correct output is produced for the GroundVM.
+
+### `-b <file>` or `--bytecode <file>`
+
+Outputs Ground bytecode (in `grbc` format) and saves it in the file `<file>`.
+
+Ground bytecode is useful for distributing software in a format where the target machine does not need Solstice installed, only the Ground VM.
+
+Run the compiled bytecode with:
+
+```sh
+ground -b <file>
+```
+
+### `-c <file>` or `--compile <file>`
+
+Compiles the Ground bytecode to assembly using the [Tram](https://chookspace.com/tram/tram) backend, outputting a binary named `<file>`.
+
+Requires Ground to be built with Tram support, and Tram to be installed on your system.
+
+This backend is experimental and does not support all features.

src/comment_conventions.md

@@ -0,0 +1 @@
+# Comment Conventions

src/fornax.md

@@ -0,0 +1,12 @@
+# "Fornax" 1.x.x
+
+Fornax will be the codename for the 1.x.x releases of Solstice. It is named after the [Fornax constellation](https://en.wikipedia.org/wiki/Fornax).
+
+## Release Target
+
+Fornax will release when:
+
+* The compiler core is stable enough to host moderately sized projects
+* The standard library is capable enough for many programming projects
+
+Fornax is not currently released.

src/functions.md

@@ -0,0 +1 @@
+# Functions

src/hello_world.md

@@ -0,0 +1,22 @@
+# Hello, World!
+
+Create a new file on your computer (preferably in a new folder) named `main.sols`. In the file, write the following:
+
+```solstice
+puts "Hello, World!"
+```
+
+Save the file, then run in your terminal:
+
+```sh
+solstice main.sols
+```
+
+Solstice will run the file for you, which should print `Hello, World!` to the console.
+
+Here's what it does:
+
+* `puts`: Stands for "put something". It's Solstice's built in "please print out this thing's current state" operator.
+* `"Hello, World!"`: A string. A string is a collection of characters. In Solstice, you denote a string by surrounding your text with double quotes (`"`).
+
+Next up: using variables!

src/installation.md

@@ -0,0 +1,11 @@
+# Installation
+
+Solstice is fully supported and tested on Linux, however should work on most UNIX-like environments. Windows support is theoretically possible, however not all features are avaliable, so use WSL, MSys, or Cygwin instead.
+
+## Which method is for you?
+
+Use a [prebuilt binary](prebuilt_binaries.md) if you're in a rush, or you can't get a compiler on your system.
+
+Use the [automated build script](automated_build_script.md) for a full install of Solstice and Ground, with maximum flexibility.
+
+Do a [manual build](building_manually.md) if you intend to contribute to the Solstice source code.

src/introduction.md

@@ -1,5 +1,7 @@
 # Introduction
 
-Welcome to the Solstice docs! For now, the documentation is in the format of a specification, which instructs you on how Solstice should behave. In future, a tutorial (similar to the Rust book) will be written which shows you each part of the language, instead of declaring it like the spec.
+Welcome to the Solstice documentation! Here we have a tutorial (starting [here](installation.md)) and a specification for the Solstice programming language.
+
+If you're new to Solstice, I'd recommend starting the tutorial, at the [installation](installation.md) page. If you've already installed Solstice, start at the [Basics](basics.md) page.
 
 Docs generated by mdBook.

src/naming_conventions.md

@@ -0,0 +1 @@
+# Naming Conventions

src/operators.md

@@ -121,3 +121,25 @@ puts x
 
 so the type checker can know what `x` is.
 
+## `use`
+
+The `use` operator lets you import code from libraries, either from in the local folder or installed in the `$SOLSTICE_LIBS` directory, which defaults to `/usr/lib/solstice`.
+
+When using `use`, Solstice will insert the selected file's contents at that position.
+
+### Local `use`
+
+Supply a string after `use` which is the path to the file to import, without the `.sols` extension.
+
+```solstice
+use "parser/Node"
+use "parser/parser"
+```
+
+### Global `use`
+
+Supply an identifier after `use` which is the name of the library to import, without the `.sols` extension.
+
+```solstice
+use io
+```

src/prebuilt_binaries.md

@@ -0,0 +1,11 @@
+# Prebuilt Binaries
+
+Solstice binaries statically linked with Ground are avaliable from the [Solstice releases page](https://chookspace.com/solstice/solstice/releases). For now, these are only for Linux x86_64, but more options may be avaliable in future. 
+
+Download the latest release, copy it into a folder in your path (such as `/usr/local/bin`) and enjoy!
+
+## Producing release binaries
+
+There is a script [on Chookspace](https://chookspace.com/solstice/builder) which builds Solstice and Ground in a container. Use this script for building production releases, and determining whether bugs are setup-specific or affect all people.
+
+Use this script to produce prebuilt binaries for the releases page.

src/structures.md

@@ -0,0 +1 @@
+# Structures

src/tutorial_comments.md

@@ -0,0 +1,37 @@
+# Comments
+
+In Solstice, there are 3 ways to do comments:
+
+## `//` (Single-Line Comment)
+
+Writing `//` tells Solstice to ignore the rest of the line.
+
+Some examples:
+
+```solstice
+puts 2 + 2 // should be 4
+
+// This variable holds the status code from checkStatus()
+statusCode = checkStatus("file.txt")
+```
+
+This comment should be used when writing your code's logic in Solstice.
+
+## `/* */` (Multiline Comment)
+
+Any text in between `/*` and `*/` will be ignored. These comments should be used to document functions and structs (we'll get to those later.)
+
+Example:
+
+```solstice
+/*
+    Adds two numbers together.
+*/
+def add(int a, int b) int {
+    return a + b
+}
+```
+
+## `#` (Shebang Comment)
+
+Use this comment only for using Solstice as a script interpreter in a shebang. Effectively the same as `//`, but we recommend using `//` over `#`.

src/tutorial_variables.md

@@ -0,0 +1,32 @@
+# Variables
+
+## Creating Variables
+
+In Solstice, you can initialize a variable using the syntax:
+
+```solstice
+name = value
+```
+
+where:
+
+* `name` is the name of your variable. You can use all letters in variable names, as well as underscores and numbers.
+  * The standard way to name your variables in Solstice is with `camelCase`.
+* `value` is some sort of value. This value can be:
+  * an integer (number with no decimal place)
+  * a double (number with a decimal place)
+  * a string (collection of characters, as seen before)
+  * a character (a single letter)
+  * a boolean (either `true` or `false`)
+
+We'll look at types of values in the next part.
+
+## Recalling Variables
+
+Recall a variable's content by using it's name:
+
+```solstice
+puts name
+```
+
+where `name` is the name of your variable.

src/values_and_types.md

@@ -0,0 +1,72 @@
+# Values and Types
+
+In Solstice, everything is a value, and every value has a type. Values can be moved around and passed to different functions, however to pass them around their type must be confirmed.
+
+## `int`
+
+An `int` is a signed (meaning either positive or negative) 8-byte integer (meaning no decimal place).
+
+Using this size, Solstice can accurately process numbers between `-9,223,372,036,854,775,807` and `9,223,372,036,854,775,807`.
+
+Integers are represented as a collection of digits not seperated by anything, such as:
+
+```solstice
+123
+7483
+423843269
+```
+
+## `double`
+
+A `double` is a signed 8-byte floating-point (meaning with a decimal place) number. 
+
+Using this size, Solstice can accurately process numbers between 15 and 17 digits long.
+
+Doubles are represented as a collection of digits, with a dot (`.`) seperating the ones and tenths positions, such as:
+
+```solstice
+3.14
+432.543
+5907432.432
+```
+
+## `string`
+
+A `string` is a collection of characters which end with a null byte (handled by Solstice).
+
+Solstice can accurately process strings of any size, provided your computer has enough memory.
+
+Strings are represented as a collection of characters surrounded by double quotes (`""`), such as:
+
+```solstice
+"Hello, World!"
+"Solstice is cool"
+"Rust kinda mid"
+```
+
+## `char`
+
+A `char` is a signed 1-byte integer, represented as an ASCII character, however can also be used to represent a single byte in a stream.
+
+Solstice can accurately process any ASCII character.
+
+Characters are represented as a single character surrounded by single quotes (`''`), such as:
+
+```solstice
+'a'
+'b'
+'c'
+```
+
+## `bool`
+
+A `bool` is a variable which can either be `true` or `false`.
+
+```solstice
+true
+false
+```
+
+## Other Types
+
+Solstice has three other types: `fun`, `template`, and `object`, but we'll cover these in the [Functions](functions.md) and [Structures](structures.md) pages.

src/vela.md

@@ -0,0 +1,26 @@
+# "Vela" 0.x.x
+
+Vela is the codename for the 0.x.x releases of Solstice. It is named after the [Vela constellation](https://en.wikipedia.org/wiki/Vela_(constellation)).
+
+## Changes
+
+Vela is the prerelease version of Solstice, and is the phase where core compiler features are added. Here are some features added in Vela to the compiler:
+
+* `puts`
+* Variables
+* Values
+* Static type system
+* `if`, `while` control flow
+* Functions
+  * Lambda/Anonymous Functions
+  * Named Functions
+  * Closures attached to functions
+* Structs
+  * Fields
+  * Methods
+  * `private` and `protected`
+  * `as`-methods
+  * Constructors, destructors, duplicators
+* Generics (in progress)
+* `pragma` directives (in progress)
+* Libraries with `use`

src/vela_0.1.0.md

@@ -0,0 +1,24 @@
+# "Vela" 0.1.0
+
+This is the very first release of Solstice! Not much to see here.
+
+This release contains:
+
+* `puts`
+* Variables
+* Values
+* Static type system
+* `if`, `while` control flow
+* Functions
+  * Lambda/Anonymous Functions
+  * Named Functions
+  * Closures attached to functions
+* Structs
+  * Fields
+  * Methods
+  * `private` and `protected`
+  * `as`-methods
+  * Constructors, destructors, duplicators
+* Generics (partially, there are many bugs)
+* `pragma` directives in the parser
+* Libraries with `use`