.envrc

+use_nix

.github/ISSUE_TEMPLATE

-**Reproduction**: [describe how you are able to reproduce ("trigger") this bug/issue.]
-
-**Expected behavior**: [describe the behavior you would expect the repro to yield.]
-
-**Actual behavior**: [describe the actual behavior, which is presented through the repro.].
-
-**Build information**: [output of `rustc -V`, `git rev-parse HEAD`, `qemu-i386 -version`, `uname -a`, `ion --version`, etc.]
-
-**Blocking/related**: [issues or PRs blocking or being related to this issue.]
-
-**Misc**: [optional: for other relevant information that should be known or cannot be described in the other fields.]
-
-------
-
-_If the above does not fit the nature of the issue feel free to modify it._

.github/PULL_REQUEST_TEMPLATE

-**Problem**: [describe the problem you try to solve with this PR.]
-
-**Solution**: [describe carefully what you change by this PR.]
-
-**Changes introduced by this pull request**:
-
-- [...]
-- [...]
-- [...]
-
-**Drawbacks**: [if any, describe the drawbacks of this pull request.]
-
-**TODOs**: [what is not done yet.]
-
-**Fixes**: [what issues this fixes.]
-
-**State**: [the state of this PR, e.g. WIP, ready, etc.]
-
-**Blocking/related**: [issues or PRs blocking or being related to this issue.]
-
-**Other**: [optional: for other relevant information that should be known or cannot be described in the other fields.]
-
-------
-
-_The above template is not necessary for smaller PRs._

.gitignore

+!.travis
+cachegrind.*
+perf.*
+git_revision.txt
 target
 manual/book
+.cargo/config
+vendor/
+vendor.tar.xz
+/window-config.ion
+manual/builtins/
+
+# Command make manual overwrites this file anyway
+manual/src/builtins.md
+
+# This file gets recreated by the command "make tests" anyway
+# with home folder of the current user aka $HOME.
+# Without this line, there is a danger of contributors committing their home folder path accidentally.
+tests/fn-root-vars.out

.gitlab-ci.yml

+image: "redoxos/redoxer"
+
+variables:
+    CARGO_HOME: $CI_PROJECT_DIR/cargo
+before_script:
+  - apt-get update -qq
+  - apt-get install -qq build-essential curl git
+
+format:
+  image: 'rustlang/rust:nightly'
+  cache:
+    key: format
+    paths:
+      - cargo/
+      - target/
+  script:
+    - rustup default nightly
+    - rustup component add rustfmt
+    - cargo +nightly fmt --all -- --check
+
+linux:
+  image: 'rust:1.65.0'
+  cache:
+    key: linux
+    paths:
+      - cargo/
+      - target/
+  script:
+    - cargo check --features=piston
+    - FULL=1 make tests
+ 
+# Deactiavted: job linux:stable does always fail right now 
+# For details see issue: https://gitlab.redox-os.org/redox-os/ion/-/issues/1027 
+# linux:stable:
+#   cache:
+#     key: linuxstable
+#     paths:
+#       - cargo/
+#       - target/
+#   script:
+#     - cargo check --features=piston
+#     - TOOLCHAIN= make tests
+
+redox:
+  cache:
+    key: redox
+    paths:
+      - cargo/
+      - target/
+  before_script:
+    - apt-get update -qq
+    - apt-get install -qq build-essential curl git
+  script:
+    - redoxer build # TODO: do test when it does not hang
+
+# Disabled until issues can be fixed
+# link-check:
+#   image: hrektts/mdbook
+#   cache:
+#     key: linkcheck
+#     paths:
+#       - cargo/
+#       - cargo/bin
+#   before_script:
+#     - apt-get update -qq
+#     - apt-get install -qq libssl-dev pkg-config build-essential curl git
+#     - test -x $CARGO_HOME/bin/mdbook-linkcheck || cargo install mdbook-linkcheck
+#   script:
+#   - PATH=$PATH:$CARGO_HOME/bin
+#   - make manual
+#   - mdbook build manual
+
+pages:
+  image: hrektts/mdbook
+  stage: deploy
+  cache:
+    key: book
+    paths:
+      - cargo/
+      - cargo/bin
+  before_script:
+    - apt-get update -qq
+    - apt-get install -qq libssl-dev pkg-config build-essential curl git
+  script:
+  - PATH=$PATH:$CARGO_HOME/bin
+  - make manual
+  - mdbook build manual
+  - mv manual/book/html public
+  artifacts:
+    paths:
+    - public
+  only:
+  - master
+
+compare-benchmarks:
+  image: rustlang/rust:nightly
+  stage: test
+  when: manual
+  allow_failure: true
+  except: [master]
+  script:
+    - apt-get update && apt-get install -y build-essential libboost-dev jq bc
+    - sh ./ci/run_benchmark.sh
+  artifacts:
+    reports:
+      junit: target/report.xml
+    paths: [target/criterion]

.gitlab/issue_templates/bug.md

+bug: description
+
+expect: outcome description
+
+related: none/#issuenumber
+
+code: input
+```
+shell code
+```
+
+expect: output
+```
+result
+```
+
+kernel: win10/win7/linux4.4/linux5.7/mac10.0/mac10.15/redox0.3.5/redox0.5.0
+
+version: `ion --version`/`git rev-parse HEAD`
+
+interaction: none/program list
+
+context: additional setup/run inside terminal multiplexer etc
+
+behavior of bash/dash/zsh/fish/oil

.gitlab/issue_templates/rfc.md

+feat: (description with motivation)
+
+BREAKING CHANGE: (effect on current programs or datastructures)
+
+perf: impact
+
+performance
+
+usability
+
+maintainability
+
+code: input
+```
+shell code
+```
+
+expect: output
+```
+result
+```
+
+reason: (for what use case is this important)
+
+context: (links, text and further literature)
+
+behavior of bash/dash/zsh/fish/oil

.gitlab/issue_templates/syntax.md

+feat: (description with motivation)
+
+BREAKING CHANGE: (effect on current programs or datastructures?)
+
+perf: impact
+
+performance
+
+usability
+
+maintainability
+
+code: input
+```
+shell code
+```
+
+expect: output
+```
+result
+```
+
+reason: (for what use case is this important)
+
+context: (links, text and further literature)
+
+behavior of bash/dash/zsh/fish/oil

.gitlab/merge_request_templates/BREAKING_CHANGE.md

+feat: description
+
+closes issue: #RFC
+
+closes issue: #bug
+
+BREAKING CHANGE: (where how and what breaks)
+
+test: unit?
+
+test: integration in (default in `tests`, otherwise explain concise)
+
+refactor: affects other tests or data structures?
+
+docs: documented?
+
+perf: performance impact?

.gitlab/merge_request_templates/feat.md

+feat: description
+
+closes issue: #featurediscussion
+
+test: unit and integration
+
+unit test?
+
+integration test in (default in `tests`, otherwise explain concise)
+
+refactor: affects other tests or data structures?
+
+docs: documented?
+
+perf: performance impact?

.gitlab/merge_request_templates/fix.md

+fix: description
+
+closes issue: #bug
+
+test: regression tested in (default in `tests`, otherwise explain concise)
+
+refactor: (affects other tests or data structures?)
+
+docs: (documented?)
+
+perf: (performance impact?)

.travis.yml

-language: rust
-rust:
-  - nightly
-sudo: false
-notifications:
-  email: false
-script:
-  - cargo build
-  - cargo test
-  - bash examples/run_examples.sh

CONTRIBUTING.md

+# Contributor Guidelines
+
+Contributors MUST:
+Comply with the templates using [conventional commit](https://www.conventionalcommits.org/en/v1.0.0-beta.4/) or **explicitly reason why not**
+
+## Merge Requests
+
+Contributors MUST:
+
+- Comply with the templates using [conventional commit](https://www.conventionalcommits.org/en/v1.0.0-beta.4/) or **explicitly reason why not**
+- For **bug fixes** fill 1. Description, 2.Related issue, 3.Regression test, 4.Refactoring statement, 6.Documentation and 7.Performance
+- For **features** fill 1. Description, 2.Related discussion, 3.Unit test, 4. Integration test, 5. Refactoring statement, 6.Documentation and 7.Performance
+- For **BREAKING CHANGE**, where valid programs are not working anymore, create a Request For Comment(RFC)
+- Format your code with `cargo +nightly fmt` before creating a commit
+- Squash commits, such that each commit clearly does a specific thing, either locally or using gitlab's custom checkbox.
+- [Adhere to a git workflow using rebase](https://medium.com/singlestone/a-git-workflow-using-rebase-1b1210de83e5)
+- Rebase upon the master branch, rather than merging it
+- [Allow us to make commits on your merge request](https://docs.gitlab.com/ee/user/project/merge_requests/allow_collaboration.html)
+
+Contributors MUST NOT:
+
+- Have merge commits in their merge requests
+- Have breaking changes without RFC
+- Have commits which do not adhere to [Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0-beta.4/) guidelines
+
+Contributors SHOULD NOT:
+
+- Worry about code style, because `cargo fmt` renders this a non-issue
+
+[conventional commit]: https://www.conventionalcommits.org/en/v1.0.0-beta.4/
+
+## Finding an issue
+
+1. Find an area to work on within the shell or one of it's related projects.
+This may be:
+
+- An existing issue which has been reported
+- A feature that is missing that you would like to develop
+- An issue you've discovered that you would like to fix
+
+2. Submit your intent to the issue board. Write into an existing issue or create a new issue.
+
+## On Unit & Integration Tests
+
+Feature addition to the code should be accompanied by unit and integration tests,
+in order to prevent issues from creating on refactoring in the future.
+Bug fixes should be combined with regression tests in order to prevent issues from 
+re-occuring in the future.
+
+If you see an area that deserves a test, feel free to add extra tests in your pull requests.
+When submitting new functionality, especially complex functionality, try to write as many
+tests as you can think of to cover all possible code paths that your function(s) might take.
+Integration tests are located in the **tests** directory, and are the most important place
+to create tests -- unit tests come second after the integration tests.
+Regression tests are both integration and unit tests, depending on the bug.
+
+Integration tests are much more useful in general, as they cover real world use cases and
+stress larger portions of the code base at once. 
+See [this section][integration test] on how integration tests are done for Ion.
+
+Yet unit tests still have their place, as
+they are able to test bits of functionality which may not necessarily be covered by existing
+integration tests.
+
+> In order to create unit tests for otherwise untestable code that depends on greater runtime
+> specifics, you should likely write your functions to accept generic inputs, where unit
+> tests can pass dummy types and environments into your functions for the purpose of testing
+> the function, whereas in practice the function is hooked up to it's appropriate types.
+
+
+## Test your code
+
+Before submitting a merge request (MR) on GitLab, ensure that you've run your tests locally and that they
+pass.
+
+You can run all tests via this command.
+
+```sh
+make tests
+```
+
+You can also run just one specific integration test via
+
+```sh
+make test.<name_of_test> 
+```
+
+To run just test "comments" for example
+
+```sh
+make test.comments
+```
+
+## Format your code
+
+In addition, format your code before submitting a MR. This will require that
+you've installed the `rustfmt` Cargo component.
+
+```sh
+cargo +nightly fmt --all
+```
+
+Now you're ready to submit your work for review!
+
+## Submitting your work for review
+
+Submitting your work on the Redox OS GitLab server can be done by creating a [merge request (MR)](https://gitlab.redox-os.org/help/user/project/merge_requests/index.md).
+
+**Important** Make sure you [enable commit edits from upstream members](https://gitlab.redox-os.org/help/user/project/merge_requests/allow_collaboration.md#enabling-commit-edits-from-upstream-members) by clicking the *"Allow commits from members who can merge to the target branch"* checkbox.
+
+## Chatroom
+
+You can join the chat of redox on maxtrix under https://matrix.to/#/#redox:matrix.org which is used by the developers too. 
+Experience with Rust is not required for contributing to Ion. There
+are ways to contribute to Ion at all levels of experience, from writing scripts in Ion and reporting
+issues, to seeking mentorship on how to implement solutions for specific issues on the issue board.
+
+## Discussion
+
+In addition to the chatroom, there's a [thread in the Redox forums](https://discourse.redox-os.org/t/ion-shell-development-discussion/682)
+that can be used for discussions relating to Ion and Ion shell development. These are mostly served
+by the GitHub issue board, but general discussions can take place there instead.
+
+## How integration tests work in Ion
+
+Integration tests are located at the folder named "tests" which is relative to the project root. 
+This is usual for rust projects. 
+Ion however does integration test via Ion/parameter input and expected output files.
+
+- An input is just an Ion or parameter file which is executed by the Ion shell. 
+  Such a file has the file extension "ion" or "params".
+- The expected output file is a normal text file 
+  which contains the expected content of the integration test.
+  Such a file has the file extension "out". 
+
+This [bash script] executes all the Ion input files with the Ion shell and compares
+their output with their corresponding output files.
+
+---
+
+### How to create an integration test in general
+
+There 2 ways of integration tests.
+
+1. Ion executes an Ion script file
+2. Ion is executed with arguments
+
+You need to create an input file and an expected output file under the folder "tests".
+The base name of the input file and its respective expected output file needs to be same.
+Only the file extension of the both files should differ. 
+Example: integration test "example_method" would have an input file "example_method.ion" 
+and an expected output file "example_method.out" under the folder "tests".
+
+---
+
+### How to create integration test where Ion executes an Ion file
+
+To create an integration test which is named "first_integration_test" 
+and is conducted by executing an Ion script file.
+
+1. Create a file named "first_integration_test.ion" 
+   with the content which Ion shell should execute
+2. Create a file named "first_integration_test.out" 
+   with the expected output 
+
+--- 
+
+### How to create integration test where Ion is executed with arguments
+
+To create an integration test which is named "first_integration_test" 
+and is conducted by executing the Ion shell with certain arguments.
+
+1. Create a file named "first_integration_test.params"
+   with the arguments which the Ion shell should be executed with.
+2. Create a file named "first_integration_test.out"
+   with the expected output
+
+Every option and value for an option goes into a new line. 
+See [params file](./tests/keybinding_fail.params) as an example.
+This example corresponds to the following command which is executed for the integration test
+
+```sh
+ion -o viemacs -c "echo 1"
+```
+
+[bash script]:./tests/run_examples.sh
+[integration test]:#how-integration-tests-work-in-ion

Cargo.toml

 [package]
-name = "ion-shell"
+
+authors = [
+    "Michael Aaron Murphy <mmstickman@gmail.com>",
+    "Jeremy Soller <jackpot51@gmail.com>",
+    "Skyler Berg <skylertheberg@gmail.com>",
+    "stratact <stratact1@gmail.com>",
+    "AdminXVII <dev.xlheureux@gmail.com>",
+    "Hunter Goldstein <hunter.d.goldstein@gmail.com>",
+    "jD91mZM2 <me@krake.one>",
+    "Agustin Chiappe Berrini <jnieve@gmail.com>",
+    "Sag0Sag0 <Sag0Sag0@users.noreply.github.com>",
+]
+build = "build.rs"
+categories = ["command-line-utilities", "config"]
 description = "The Ion Shell"
-repository = "https://github.com/redox-os/ion"
-version = "1.0.5"
+documentation = "https://doc.redox-os.org/ion-manual/"
+edition = "2018"
+keywords = ["shell", "script", "program", "config", "configuration"]
 license-file = "LICENSE"
+name = "ion-shell"
 readme = "README.md"
-authors = [
-  "Michael Aaron Murphy <mmstickman@gmail.com>",
-  "Hunter Goldstein <hunter.d.goldstein@gmail.com>",
-  "Skyler Berg <skylertheberg@gmail.com>",
-  "Jeremy Soller <jackpot51@gmail.com>",
-  "Michael Gattozzi <mgattozzi@gmail.com>",
-  "Łukasz Niemier <lukasz@niemier.pl>",
+repository = "https://gitlab.redox-os.org/redox-os/ion"
+version = "1.0.0-alpha"
+rust-version = "1.65.0"
+
+[badges]
+gitlab = { repository = "https://gitlab.redox-os.org/redox-os/ion", branch = "master" }
+maintenance = { status = "experimental" }
+
+[features]
+man = ["builtins-proc/man"]
+piston = ["piston-ai_behavior", "piston_window", "piston2d-sprite"]
+unicode = ["regex/unicode"]
+
+[workspace]
+members = [
+    "members/builtins-proc",
+    "members/ranges",
+    "members/scopes-rs",
+    "members/types-rs",
 ]
-build = "build.rs"
+
+[dev-dependencies]
+criterion = "0.3"
+serial_test = "*"
+serial_test_derive = "*"
+
+[[bench]]
+name = "terminator"
+harness = false
+
+[[bench]]
+name = "statement"
+harness = false
+
+[[example]]
+name = "window"
+required-features = ["piston"]
 
 [[bin]]
 name = "ion"
 path = "src/main.rs"
 
-## Shared Dependencies
-
 [dependencies]
-# Provides XDG app directory support
-app_dirs = "1.1.1"
-# Provides methods for bitwise flag operations
-bitflags = "0.9.1"
-# Provides inline arithmetic expression and `calc` functionality
-calculate = {git = "https://github.com/redox-os/calc.git"}
-# A faster hashing algorithm for the hash maps in the shell.
-fnv = "1.0"
-# Performs globbing on words that are detected to be potentially globbable.
-glob = "0.2"
-# Provides a macro for lazily-evalulated statics
-lazy_static = "0.2"
-# Provides the line editor / prompt for the shell
-liner = "0.4"
-# Provides permutations of strings in brace expansions
+calculate = { git = "https://gitlab.redox-os.org/redox-os/calc", rev = "d2719efb67ab38c4c33ab3590822114453960da5" }
+thiserror = "1.0"
+glob = "0.3"
+redox_liner = { git = "https://gitlab.redox-os.org/redox-os/liner" }
+rand = "0.7"
+regex = { version = "1.3", default-features = false, features = [
+    "std",
+    "perf",
+] }
+small = { git = "https://gitlab.redox-os.org/redox-os/small", features = [
+    "std",
+] }
+smallvec = "1.4"
+unicode-segmentation = "1.6"
+ion-ranges = { version = "0.1", path = "members/ranges" }
+scopes = { version = "0.1", path = "members/scopes-rs" }
+types-rs = { version = "0.1", path = "members/types-rs" }
+builtins-proc = { version = "0.1", path = "members/builtins-proc" }
+itertools = "0.9"
+lexical = "5.2"
+object-pool = "0.6"
+auto_enums = "0.7"
+atty = "0.2"
 permutate = "0.3"
-# Enables strings to be stored inline on the stack, when possible.
-smallstring = "0.1"
-# Same as the above, but for vectors.
-smallvec = "0.4"
-# Provides grapheme-based string iterators.
-unicode-segmentation = "1.2"
-# Rusts regex crate
-regex = "0.2"
-
-## Redox Dependencies
-
-[target.'cfg(target_os = "redox")'.dependencies]
-# Provides access to Redox syscalls for signals/job control.
-redox_syscall = "0.1"
-
-## *nix Dependencies (Linux, Mac OS, BSDs)
-
-[target.'cfg(all(unix, not(target_os = "redox")))'.dependencies]
-# Required to access some *nix-specific syscalls for signals/job control.
-libc = "0.2"
-# A higher level abstraction of libc-acquired syscalls for signals/job control.
-nix = "0.8"
-# Obtains user directories
-users = "0.5.1"
-# Enables loading plugins
-libloading = "0.4"
-
-[build-dependencies]
-ansi_term = "0.9"
-version_check = "0.1.3"
+xdg = "2.4"
+#nix = "0.23"
+# FIXME: Needed because of https://github.com/nix-rust/nix/commit/ff6f8b8a26c8d61f4341e441acf405402b46a430
+nix = { git = "https://github.com/nix-rust/nix.git", rev = "ff6f8b8a" }
+mktemp = "0.4"
+
+
+# window example
+piston-ai_behavior = { version = "0.31", optional = true }
+piston_window = { version = "0.120", optional = true }
+piston2d-sprite = { version = "0.58", optional = true }
+
+[target."cfg(all(unix, not(target_os = \"redox\")))".dependencies]
+users = "0.10"
+
+[target."cfg(target_os = \"redox\")".dependencies]
+redox_users = "0.4"
+
+[target."cfg(target_os = \"dragonfly\")".dependencies]
+errno-dragonfly = "0.1.1"
+
+[lib]
+path = "src/lib/lib.rs"
+
+[profile.dev]
+opt-level = 0
+debug = true
 
 [profile.release]
-# debug = true
-# rustflags = [ "-C", "target-cpu=native"]
 lto = true
 panic = "abort"
+
+# Required to make `cargo vendor` work
+[patch.crates-io]
+redox_liner = { git = "https://gitlab.redox-os.org/redox-os/liner" }

Makefile

+prefix ?= usr/local
+BINARY = $(prefix)/bin/ion
+RELEASE = debug
+TOOLCHAIN ?= 1.65.0
+
+GIT_REVISION=git_revision.txt
+SRC=Cargo.toml Cargo.lock $(shell find src members -type f -wholename '*src/*.rs')
+VENDOR=.cargo/config vendor.tar.xz
+
+DEBUG ?= 0
+ifeq ($(DEBUG),0)
+	ARGS += --release
+	RELEASE = release
+endif
+
+VENDORED ?= 0
+ifeq ($(VENDORED),1)
+	ARGSV += --frozen
+endif
+
+REDOX ?= 0
+ifeq ($(REDOX),1)
+	undefine ARGSV
+	ARGS += --target x86_64-unknown-redox
+	TOOLCHAIN = nightly
+endif
+
+RUSTUP ?= 1
+ifeq ($(RUSTUP),1)
+	TOOLCHAIN_ARG = +$(TOOLCHAIN)
+endif
+
+.PHONY: tests all clean distclean install uninstall manual
+
+all: $(SRC) $(GIT_REVISION)
+ifeq ($(REDOX),1)
+	mkdir -p .cargo
+	grep redox .cargo/config || cat redox_linker >> .cargo/config
+endif
+ifeq ($(VENDORED),1)
+	tar pxf vendor.tar.xz
+endif
+	cargo $(TOOLCHAIN_ARG) build $(ARGS) $(ARGSV)
+
+manual:
+	rm -rf manual/builtins
+	mkdir manual/builtins
+	cargo build --features man
+	echo -n "# Builtin commands" > manual/src/builtins.md
+	for man in manual/builtins/*; do \
+		echo "" >> manual/src/builtins.md; \
+		echo -n "## " >> manual/src/builtins.md; \
+		cat $$man >> manual/src/builtins.md; \
+	done
+
+tests:
+	cargo $(TOOLCHAIN_ARG) test $(ARGSV)
+	TOOLCHAIN=$(TOOLCHAIN) bash tests/run_examples.sh
+	for crate in members/*; do \
+		cargo $(TOOLCHAIN_ARG) test $(ARGSV) --manifest-path $$crate/Cargo.toml || exit 1; \
+	done
+
+test.%:
+	TOOLCHAIN=$(TOOLCHAIN) bash tests/run_examples.sh $@
+
+vendor: $(VENDOR)
+
+$(VENDOR):
+	rm -rf .cargo vendor vendor.tar.xz
+	mkdir -p .cargo
+	cargo vendor | head -n -1 > .cargo/config
+	echo 'directory = "vendor"' >> .cargo/config
+	tar pcfJ vendor.tar.xz vendor
+	rm -rf vendor
+
+update-shells:
+	if ! grep ion /etc/shells >/dev/null; then \
+		echo $(BINARY) >> /etc/shells; \
+	else \
+		shell=$(shell grep ion /etc/shells); \
+		if [ $$shell != $(BINARY) ]; then \
+			sed -i -e "s#$$shell#$(BINARY)#g" /etc/shells; \
+		fi \
+	fi
+

README.md

+# Introduction
+
+Ion is a modern system shell that features a simple, yet powerful, syntax. It is written entirely
+in Rust, which greatly increases the overall quality and security of the shell. It also offers a
+level of performance that exceeds that of Dash, when taking advantage of Ion's features. While it
+is developed alongside, and primarily for, RedoxOS, it is a fully capable on other \*nix platforms.
+
 # Ion Shell
 
-[![Build Status](https://travis-ci.org/redox-os/ion.svg)](https://travis-ci.org/redox-os/ion)
 [![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
-[![crates.io](http://meritbadge.herokuapp.com/ion-shell)](https://crates.io/crates/ion-shell)
-![LOC](https://tokei.rs/b1/github/redox-os/ion)
+[![crates.io](https://meritbadge.herokuapp.com/ion-shell)](https://crates.io/crates/ion-shell)
+[![Documentation](https://img.shields.io/badge/documentation-blue)](https://doc.redox-os.org/ion-manual)
 
-# New Ion MdBook
+> Ion is still a WIP, and both its syntax and rules are subject to change over time. It is
+> still quite a ways from becoming stabilized, but we are getting very close. Changes to the
+> syntax at this time are likely to be minimal.
 
-We are providing our manual for Ion in the form of a markdown-based book, which is accessible via:
+# Ion Specification
 
-- The official page for Ion's manual on Redox's website: https://doc.redox-os.org/ion-manual/
-- Installing the mdbook via our `setup.ion` script and having Ion open an offline copy via `ion-docs`.
-- Building and serving the book in the **manual** directory yourself with [mdBook](https://github.com/azerupi/mdBook)
+Ion has a RFC process for language proposals. Ion's formal specification is located within the
+[rfcs](https://gitlab.redox-os.org/redox-os/ion/tree/rfcs) branch. The RFC process is still in
+the early stages of development, so much of the current and future implementation ideas have
+yet to be written into the specification.
 
-# Introduction
+# Ion Manual
 
-Ion is a modern system shell that features a simple, yet powerful, syntax. It is written entirely
-in Rust, which greatly increases the overall quality and security of the shell, eliminating the
-possibilities of a [ShellShock](http://www.wikiwand.com/en/Shellshock_(software_bug))-like vulnerability, and making development easier. It also
-offers a level of performance that exceeds that of Dash, when taking advantage of Ion's features.
-While it is developed alongside, and primarily for, RedoxOS, it is a fully capable on other *nix
-platforms, and we are currently searching for a Windows developer to port it to Windows.
-
-# Goals
-
-Syntax and feature decisions for Ion are made based upon three measurements: is the feature useful,
-is it simple to use, and will it's implementation be efficient to parse and execute? A feature is
-considered useful if there's a valid use case for it, in the concept of a shell language. The
-syntax for the feature should be simple for a human to read and write, with extra emphasis on
-readability, given that most time is spent reading scripts than writing them. The implementation
-should require minimal to zero heap allocations, and be implemented in a manner that requires
-minimal CPU cycles (so long as it's also fully documented and easy to maintain!).
-
-It should also be taken into consideration that shells operate entirely upon strings, and therefore
-should be fully equipped for all manner of string manipulation capabilities. That means that users
-of a shell should not immediately need to grasp for tools like **cut**, **sed**, and **awk**. Ion
-offers a great deal of control over slicing and manipulating text. Arrays are treated as first
-class variables with their own unique **@** sigil. Strings are also treated as first class
-variables with their own unique **$** sigil. Both support being sliced with **[range]**, and they
-each have their own supply of methods.
-
-# Why Not POSIX?
-
-If Ion had to follow POSIX specifications, it wouldn't be half the shell that it is today, and
-there'd be no solid reason to use Ion over any other existing shell, given that it'd basically be
-the same as every other POSIX shell. Redox OS itself doesn't follow POSIX specifications, and
-neither does it require a POSIX shell for developing Redox's userspace. It's therefore not meant
-to be used as a drop-in replacement for Dash or Bash. You should retain Dash/Bash on your system
-for execution of Dash/Bash scripts, but you're free to write new scripts for Ion, or use Ion as
-the interactive shell for your user session. Redox OS, for example, also contains Dash for
-compatibility with software that depends on POSIX scripts.
-
-That said, Ion's foundations are heavily inspired by POSIX shell syntax. If you have experience
-with POSIX shells, then you already have a good idea of how most of Ion's core features operate. A
-quick sprint through this documentation will bring you up to speed on the differences between our
-shell and POSIX shells. Namely, we carry a lot of the same operators: **$**, **|**, **||**, **&**,
-**&&**, **>**, **<**, **<<**, **<<<**, **$()**, **$(())**.  Yet we also offer some functionality
-of our own, such as **@**, **@()**, **$method()**, **@method()**, **^|**, **^>**, **&>**, **&|**.
-Essentially, we have taken the best components of the POSIX shell specifications, removed the bad
-parts, and implemented even better features on top of the best parts. That's how open source
-software evolves: iterate, deploy, study, repeat.
-
-# Compile / Install Instructions
-
-Rust 1.19 is the minimum requirement for compiling Ion. Simplest way to obtain Rust/Cargo is by
-installing the [Rustup toolchain manager](https://rustup.rs/), in the event that your OS does
-not ship Rust natively, or if you want more flexibility in Rust compilation capabilities.
-
-Then, it's just a matter of performing one of the following methods:
-
-## Install Latest Stable Version From Crates.io
-
-Use the `--force` flag when updating a binary that's already installed with cargo.
+[The Ion manual online](https://doc.redox-os.org/ion-manual) 
+is generated automatically on each commit via [mdBook](https://github.com/azerupi/mdBook) and hosted on Redox OS's website.
+
+**Building the manual for local reference**
+
+Sources for the manual are located in the `manual` directory.
+
+1. Build the documentation file for the builtins 
+
+```sh
+make manual
+```
+
+2. Then build the rest of the Ion manual via mdbook
 
 ```sh
-cargo install ion-shell
+mdbook build manual
 ```
 
-## Install Direct From Git
+Or you can build and open it in the your default browser via 
 
 ```sh
-cargo install --git https://github.com/redox-os/ion/
+mdbook serve manual --open
 ```
 
-## Build Locally
+Or you can build and host the manual on your localhost via
 
 ```sh
-git clone https://github.com/redox-os/ion/
+mdbook serve manual 
+```
+
+# Ion library example
+
+See the [examples folder](https://gitlab.redox-os.org/redox-os/ion/tree/master/examples) and the [Parallelion project](https://gitlab.redox-os.org/AdminXVII/parallelion)
+
+# Packages
+
+## Pop!\_OS / Ubuntu
+
+The following PPA supports the 18.04 (bionic) and 19.04 (disco) releases. Bionic builds were made using the Pop\_OS PPA's rustc 1.39.0 package.
+
+```
+sudo add-apt-repository ppa:mmstick76/ion-shell
+```
+
+# Developer set up
+
+Those who are developing software with Rust should install the [Rustup toolchain manager](https://rustup.rs/).
+After installing rustup, run `rustup override set 1.56.0` to set your Rust toolchain to the version that Ion is
+targeting at the moment. To build for Redox OS, `rustup override set nightly` is required to build the Redox
+dependencies.
+
+# Build dependencies
+
+Please ensure that both cargo and rustc 1.56.0 or higher is installed for your system.
+Release tarballs have not been made yet due to Ion being incomplete in a few remaining areas.
+
+# Installation 
+
+## Installation of Ion shell for one user 
+
+```sh
+git clone https://gitlab.redox-os.org/redox-os/ion/
 cd ion
-cargo build --release
+cargo install --path=. --force 
 ```
 
-# Git Plugin
+This way the ion executable will be installed into the folder "~/.cargo/bin"
 
-Plugins support within Ion is still a work in progress, and so the plugin architecture is likely to change. That said,
-there's an official git plugin that can be installed to experiment with the existing plugin namespaces plugin support.
-To install the git plugin, first install ion, and then execute the following:
+As an alternative you can do it like this
 
-```ion
-./setup.ion install plugins
+```sh
+git clone https://gitlab.redox-os.org/redox-os/ion/
+cd ion
+cargo build --release 
+# Install to path which is included in the $PATH enviromnent variable
+DESTDIR=~/.local/bin bash/install.sh
 ```
 
-It can be tested out by navigating to a directory within a git repository, and running the following:
+## Installation of Ion shell system wide, for all users
 
-```ion
-echo Current Branch: ${git::branch}${git::modified_count}${git::untracked_count}
+```sh
+git clone https://gitlab.redox-os.org/redox-os/ion/
+cd ion
+cargo build --release 
+sudo DESTDIR=/usr/local/bin bash/install.sh
+# Optional: Do this if Ion shell shoulb be login shell on your system
+sudo make update-shells prefix=/usr
 ```
 
+# Ion plugins
+
+There are plugins for ion. These plugins are additional aliases and function definitions written in 
+Ion for Ion. They can be found under this [repository](https://gitlab.redox-os.org/redox-os/ion-plugins).
+
 # Vim/NeoVim Syntax Highlighting Plugin
 
-We do have an [officially-supported syntax highlighting plugin](https://github.com/vmchale/ion-vim) for all the
-vim/nvim users out there.
+For vim/nvim users there is an [officially-supported syntax highlighting plugin](https://gitlab.redox-os.org/redox-os/ion-vim).
 
 ```vimscript
 Plugin 'vmchale/ion-vim'
 ```
 
-![Screenshot of Syntax Highlighting](http://i.imgur.com/JzZp7WT.png)
+![Vim Syntax Highlighting](.gitlab/vim_syntax.png)
+
+# Emacs Syntax Highlighting Plugin
+
+For emacs users there is a [kindly-supported syntax highlighting plugin](https://github.com/iwahbe/ion-mode).
+
+```emacs
+(add-to-list 'load-path  (expand-file-name "/path/to/ion-mode"))
+(require 'ion-mode)
+(autoload 'ion-mode (locate-library "ion-mode") "Ion majore mode" t)
+(add-to-list 'auto-mode-alist '("\\.ion\\'" . ion-mode))
+(add-to-list 'auto-mode-alist '("/ion/initrc" . ion-mode))
+```
+
+![Emacs Syntax Highlighting](.gitlab/emacs_syntax.png)
+
+# Lsp /IDE support
+
+There is a LSP-server for the scripting language of this shell. 
+You can install the LSP-server via crates.io to get IDE support like error messages for an code editor or IDE which understands the client side of LSP. Link to LSP server on crates.io : https://crates.io/crates/ion_shell_lsp_server .
+The source code of the LSP server can be found here: https://gitlab.redox-os.org/redox-os/ion_lsp .

bash/distclean.sh

+#!/usr/bin/env bash
+
+rm -rf vendor vendor.tar.xz .cargo git_revision.txt
+cargo clean