.envrc

+use_nix

.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: 'rust:latest'
+image: "redoxos/redoxer"
 
 variables:
     CARGO_HOME: $CI_PROJECT_DIR/cargo
@@ -6,29 +6,102 @@ before_script:
   - apt-get update -qq
   - apt-get install -qq build-essential curl git
 
-linux:
+format:
+  image: 'rustlang/rust:nightly'
+  cache:
+    key: format
+    paths:
+      - cargo/
+      - target/
   script:
-    - cargo build
-    - make tests
+    - 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:
-  variables:
-    CC: "x86_64-unknown-redox-gcc"
+  cache:
+    key: redox
+    paths:
+      - cargo/
+      - target/
   before_script:
     - apt-get update -qq
-    - apt-get install -qq build-essential curl git gnupg software-properties-common apt-transport-https
-    - apt-key adv --keyserver keyserver.ubuntu.com --recv-keys AA12E97F0881517F
-    - add-apt-repository 'deb https://static.redox-os.org/toolchain/apt /'
-    - apt-get update -qq && apt-get install -qq x86-64-unknown-redox-gcc
-    - rustup default nightly-2018-07-18
-    - rustup target add x86_64-unknown-redox
+    - apt-get install -qq build-essential curl git
   script:
-    - make REDOX=1
+    - 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/
-      - target/
+      - 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?)

CONTRIBUTING.md

-## Find an issue
+# Contributor Guidelines
 
-First, find an area to work on within the shell or one of it's related projects.
+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
 
-Once you have found something that you want to work on, submit your intent to
-the issue board, either by creating an issue for an issue which does not exist,
-or commenting on an issue that you are working on it.
+2. Submit your intent to the issue board. Write into an existing issue or create a new issue.
 
 ## On Unit & Integration Tests
 
-Changes made to the code should normally be accompanied by both unit and integration tests,
-in order to prevent these issues from re-occuring in the future.
+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 **examples** directory, and are the most important place
+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. Yet unit tests still have their place, as
+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.
 
@@ -32,30 +67,51 @@ integration tests.
 > 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 PR, ensure that you've run your tests locally and that they
-pass. This can be done by running the following two commands:
+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
-cargo +nightly test --lib && bash examples/run_examples/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 PR. This will require that
+In addition, format your code before submitting a MR. This will require that
 you've installed the `rustfmt` Cargo component.
 
 ```sh
-cargo +nightly fmt
+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
 
-Send an email to [info@redox-os.org](mailto:info@redox-os.org) to request invitation for joining
-the developer chatroom for Ion. Experience with Rust is not required for contributing to Ion. There
+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.
 
@@ -64,3 +120,68 @@ issues, to seeking mentorship on how to implement solutions for specific issues
 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

@@ -5,62 +5,120 @@ authors = [
     "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"
+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"
 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/braces", "members/builtins", "members/lexers", "members/sys",
-    "members/ranges"
+    "members/builtins-proc",
+    "members/ranges",
+    "members/scopes-rs",
+    "members/types-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"
 
-[build-dependencies]
-ansi_term = "0.11"
-version_check = "0.1.3"
-
 [dependencies]
-bitflags = "1.0"
-calculate = "0.5"
-failure = "0.1"
-failure_derive = "0.1"
-fnv = "1.0"
-glob = "0.2"
-itoa = "0.4"
-lazy_static = "1.0"
-liner = { git = "https://gitlab.redox-os.org/redox-os/liner" }
-rand = "0.5"
-regex = "1.0"
-small = { git = "https://gitlab.redox-os.org/redox-os/small", features = ["std"] }
-smallvec = "0.6"
-unicode-segmentation = "1.2"
-xdg = { git = "https://github.com/whitequark/rust-xdg" }
-ion_braces = { path = "members/braces" }
-ion_builtins = { path = "members/builtins" }
-ion_lexers = { path = "members/lexers" }
-ion_sys = { path = "members/sys" }
-ion_ranges = { path = "members/ranges" }
+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"
+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]
 lto = true
 panic = "abort"
 
+# Required to make `cargo vendor` work
 [patch.crates-io]
-liner = { git = "https://gitlab.redox-os.org/redox-os/liner" }
-redox_syscall = { git = "https://gitlab.redox-os.org/redox-os/syscall.git", branch = "relibc" }
\ No newline at end of file
+redox_liner = { git = "https://gitlab.redox-os.org/redox-os/liner" }

Makefile

 prefix ?= usr/local
 BINARY = $(prefix)/bin/ion
 RELEASE = debug
-DEBUG ?= 0
+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
 
-ifeq (0, $(DEBUG))
+DEBUG ?= 0
+ifeq ($(DEBUG),0)
 	ARGS += --release
 	RELEASE = release
 endif
 
-ifeq (1,$(REDOX))
+VENDORED ?= 0
+ifeq ($(VENDORED),1)
+	ARGSV += --frozen
+endif
+
+REDOX ?= 0
+ifeq ($(REDOX),1)
+	undefine ARGSV
 	ARGS += --target x86_64-unknown-redox
+	TOOLCHAIN = nightly
 endif
 
-.PHONY: all clean distclean install uninstall
+RUSTUP ?= 1
+ifeq ($(RUSTUP),1)
+	TOOLCHAIN_ARG = +$(TOOLCHAIN)
+endif
 
-all: .cargo/config
-	if [ -f vendor.tar.xz ]; \
-	then \
-		tar pxf vendor.tar.xz; \
-		cargo build $(ARGS) --frozen; \
-	else \
-		cargo build $(ARGS); \
-	fi
+.PHONY: tests all clean distclean install uninstall manual
 
-clean:
-	cargo clean
+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)
 
-distclean:
-	rm -rf vendor vendor.tar.xz .cargo
+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 test --manifest-path members/braces/Cargo.toml
-	cargo test --manifest-path members/builtins/Cargo.toml
-	cargo test --manifest-path members/lexers/Cargo.toml
-	cargo test --manifest-path members/ranges/Cargo.toml
-	cargo test 
-	bash examples/run_examples.sh
+	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
 
-install:
-	install -Dm0755 target/$(RELEASE)/ion $(DESTDIR)/$(BINARY)
+test.%:
+	TOOLCHAIN=$(TOOLCHAIN) bash tests/run_examples.sh $@
 
-uninstall:
-	rm $(DESTDIR)/$(BINARY)
+vendor: $(VENDOR)
 
-.cargo/config:
+$(VENDOR):
+	rm -rf .cargo vendor vendor.tar.xz
 	mkdir -p .cargo
-	if [ -f vendor.tar.xz ]; then \
-		cp vendor_config $@; \
-	else \
-		cp nonvendor_config $@; \
-	fi \
-
-vendor.tar.xz:
-	cargo vendor
+	cargo vendor | head -n -1 > .cargo/config
+	echo 'directory = "vendor"' >> .cargo/config
 	tar pcfJ vendor.tar.xz vendor
 	rm -rf vendor
 
-vendor: .cargo/config vendor.tar.xz
-
 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 \
-			before=$$(echo $$shell | sed 's/\//\\\//g'); \
-			after=$$(echo $(BINARY) | sed 's/\//\\\//g'); \
-			sed -i -e "s/$$before/$$after/g" /etc/shells; \
+			sed -i -e "s#$$shell#$(BINARY)#g" /etc/shells; \
 		fi \
 	fi
+

README.md

@@ -9,6 +9,7 @@ is developed alongside, and primarily for, RedoxOS, it is a fully capable on oth
 
 [![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 [![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)
 
 > 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
@@ -23,41 +24,127 @@ yet to be written into the specification.
 
 # Ion Manual
 
-The Ion manual is generated automatically on each commit via [mdBook](https://github.com/azerupi/mdBook).
-The manual is located [here](https://doc.redox-os.org/ion-manual/) on Redox OS's website. It is
-also included in the source code for Ion, within the **manual** directory, which you may build
-with **mdbook**.
+[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.
 
-# Build dependencies
+**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
+mdbook build manual
+```
+
+Or you can build and open it in the your default browser via 
+
+```sh
+mdbook serve manual --open
+```
+
+Or you can build and host the manual on your localhost via
+
+```sh
+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 default 1.28.0` to set your Rust toolchain to the version that Ion is
-targeting at the moment. To build for Redox OS, `rustup default nightly` is required to build the Redox
+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.
 
-> Distribution packagers must ensure that their distribution has packaged both cargo and rustc 1.28.0.
-> Distribution packagers should also currently build Ion from git. Release tarballs have not been made yet
-> due to the shell being incomplete in a few remaining areas.
+# 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 
 
-# Compile instructions
+## Installation of Ion shell for one user 
 
 ```sh
 git clone https://gitlab.redox-os.org/redox-os/ion/
 cd ion
-make
-sudo make install prefix=/usr
-sudo make update-shells
+cargo install --path=. --force 
 ```
 
-> To compile in DEBUG mode, pass `DEBUG=1` as an argument to `make`
+This way the ion executable will be installed into the folder "~/.cargo/bin"
+
+As an alternative you can do it like this
+
+```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
+```
+
+## Installation of Ion shell system wide, for all users
+
+```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://gitlab.redox-os.org/redox-os/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](https://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

bash/install.sh

+#!/usr/bin/env bash
+
+RELEASE='target/release/ion'
+
+if [[ ! -f "$RELEASE" ]]; then
+  echo "$RELEASE does not exit. Please run (cargo build --release) before"
+  exit 1
+fi
+
+if [[ ! -d "${DESTDIR}" ]]; then
+  echo "Target folder ${DESTDIR} where the ion shell executable is to be installed, does not exits. Please ensure the folder exits" 
+  exit 1
+fi
+
+install -Dm0755 "$RELEASE" "${DESTDIR}/ion"

bash/version.sh

+#!/usr/bin/env bash
+
+git rev-parse HEAD > git_revision.txt

benches/calls.txt

+qaonukpt
+aeqpqwxv
+suspend
+qbikkjoy
+help
+true
+llempzef
+alias
+hagppque
+olbhijpd
+lhgmydgq
+fn
+xuirqppr
+bg
+rdpngwtr
+popd
+qjonappg
+isatty
+fjxnjdcv
+xvvqgbda
+dtowcqel
+tuhlmnwv
+uxfdueiz
+rcrrmexe
+pgnuuyzu
+kbxlargm
+tkrzcapt
+gnrdqkfm
+contains
+starts-with
+type
+gwvisqpo
+bdinggto
+xwlztjsx
+iwepsrfz
+lqssdiem
+tbohximc
+ends-with
+zrgzwwvx
+cezvmwvc
+random
+pijczhyk
+history
+ohosyvvr
+matches
+xnoqyzqg
+exit
+test
+zawqmsmj
+read
+lswqkzoh
+ifszbrtt
+eosrvadi
+ajcyiqqh
+is
+djcfrkoe
+kptesdea
+jlacsdip
+cd
+qzafunhq
+hcylaiir
+jknabygk
+ysapelqf
+lxlkcxzz
+wgcqkjyh
+thrjmpea
+cpxqmfom
+pushd
+fxuxznrd
+lueaxesf
+status
+gaqbnmei
+ubbokbat
+ufwjnpxb
+bool
+tmnaokwm
+fyiuysrz
+nfzxwkwz
+ughirptq
+source
+yaqacdcx
+lfjdhamz
+bslydqaq
+dhekmipk
+uekytygj
+obupdgtg
+fg
+ssvomqow
+disown
+mvmvbwgy
+unalias
+rtvvibsz
+dikuzfes
+grjqxefn
+eval
+hnabnohc
+akozolzn
+vgecngwb
+ymbbjyqm
+drop
+ecaqmokz
+exec
+vsinblzi
+which
+olqrykru
+rtrfrhqj
+eq
+wcufcnow
+olpkjaec
+wqysdkmo
+fwruleaq
+exists
+echo
+krqrpkbe
+sdvphfxz
+calc
+bumnoytn
+voimtbwi
+dynqtlbb
+jqfzilwp
+wpvhibrq
+ihnrmqmq
+azhuqdvb
+dsalzuhx
+ialmytde
+enswgpme
+jvwvqubj
+false
+dirs
+wait
+ayfgyopw
+jobs
+zocvwdzj
+sgtdofpj
+xnsbzczc
+yhjreitd
+tanglida
+stkzavte
+gfjeqxkw
+set