.gitignore

@@ -9,3 +9,11 @@ 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

@@ -9,6 +9,7 @@ before_script:
 format:
   image: 'rustlang/rust:nightly'
   cache:
+    key: format
     paths:
       - cargo/
       - target/
@@ -18,49 +19,70 @@ format:
     - cargo +nightly fmt --all -- --check
 
 linux:
-  image: 'rust:1.39.0'
+  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
 
-linux:stable:
+redox:
   cache:
+    key: redox
     paths:
       - cargo/
       - target/
-  script:
-    - cargo check --features=piston
-    - TOOLCHAIN= make tests
-
-redox:
   before_script:
     - apt-get update -qq
     - apt-get install -qq build-essential curl git
-    - git clone --single-branch --branch=add-redox-support --depth=1 https://github.com/AdminXVII/nix
-    - mkdir .cargo
-    - echo 'paths = [ "nix" ]' >> .cargo/config
-    - cargo clean
   script:
-    - redoxer test
+    - redoxer build # TODO: do test when it does not hang
 
-link-check:
-  image: hrektts/mdbook
-  before_script:
-    - apt-get update -qq
-    - apt-get install -qq libssl-dev pkg-config build-essential curl git
-    - (test -x $HOME/.cargo/bin/mdbook-linkcheck || cargo install mdbook-linkcheck)
-  script:
-  - make manual
-  - mdbook build manual
+# 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

CONTRIBUTING.md

@@ -55,7 +55,10 @@ 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.
 
@@ -64,13 +67,28 @@ 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 merge request (MR) on GitLab, ensure that you've run your tests locally and that they
-pass. This can be done by running the following two commands:
+pass.
+
+You can run all tests via this command.
 
 ```sh
-cargo +nightly test --lib && bash tests/run_examples.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
@@ -79,12 +97,12 @@ 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!
 
-## Sumbitting 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).
 
@@ -92,8 +110,8 @@ Submitting your work on the Redox OS GitLab server can be done by creating a [me
 
 ## 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.
 
@@ -102,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

@@ -12,29 +12,34 @@ authors = [
     "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"
-edition = "2018"
-keywords = ["shell", "script", "program", "config", "configuration"]
-categories = ["command-line-utilities", "config"]
-documentation = "https://doc.redox-os.org/ion-manual/"
+rust-version = "1.65.0"
 
 [badges]
 gitlab = { repository = "https://gitlab.redox-os.org/redox-os/ion", branch = "master" }
 maintenance = { status = "experimental" }
 
 [features]
-advanced_arg_parsing = []
 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" ]
+members = [
+    "members/builtins-proc",
+    "members/ranges",
+    "members/scopes-rs",
+    "members/types-rs",
+]
 
 [dev-dependencies]
 criterion = "0.3"
@@ -58,41 +63,47 @@ name = "ion"
 path = "src/main.rs"
 
 [dependencies]
-calculate = { git = "https://gitlab.redox-os.org/redox-os/calc" }
-err-derive = "0.2"
+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 = "0.6"
-unicode-segmentation = "1.3"
+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.8"
-lexical = "4.0"
-object-pool = "0.3.1"
-auto_enums = "0.6"
-structopt = "0.3"
+itertools = "0.9"
+lexical = "5.2"
+object-pool = "0.6"
+auto_enums = "0.7"
 atty = "0.2"
 permutate = "0.3"
-xdg = "2.1"
-nix = { git = "https://github.com/AdminXVII/nix", branch = "add-redox-support-bis" }
+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.105", 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.9"
+users = "0.10"
 
 [target."cfg(target_os = \"redox\")".dependencies]
-redox_users = "0.3"
+redox_users = "0.4"
 
 [target."cfg(target_os = \"dragonfly\")".dependencies]
 errno-dragonfly = "0.1.1"
@@ -100,11 +111,14 @@ 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]
-termion = { git = "https://gitlab.redox-os.org/redox-os/termion" }
 redox_liner = { git = "https://gitlab.redox-os.org/redox-os/liner" }

Makefile

 prefix ?= usr/local
 BINARY = $(prefix)/bin/ion
 RELEASE = debug
-TOOLCHAIN ?= 1.39.0
+TOOLCHAIN ?= 1.65.0
 
 GIT_REVISION=git_revision.txt
 SRC=Cargo.toml Cargo.lock $(shell find src members -type f -wholename '*src/*.rs')
@@ -48,19 +48,11 @@ manual:
 	cargo build --features man
 	echo -n "# Builtin commands" > manual/src/builtins.md
 	for man in manual/builtins/*; do \
-		echo -n "\n\n## " >> manual/src/builtins.md; \
+		echo "" >> manual/src/builtins.md; \
+		echo -n "## " >> manual/src/builtins.md; \
 		cat $$man >> manual/src/builtins.md; \
 	done
 
-clean:
-	cargo clean
-
-distclean: clean
-	rm -rf vendor vendor.tar.xz .cargo git_revision.txt
-
-format:
-	cargo +nightly fmt --all
-
 tests:
 	cargo $(TOOLCHAIN_ARG) test $(ARGSV)
 	TOOLCHAIN=$(TOOLCHAIN) bash tests/run_examples.sh
@@ -68,19 +60,11 @@ tests:
 		cargo $(TOOLCHAIN_ARG) test $(ARGSV) --manifest-path $$crate/Cargo.toml || exit 1; \
 	done
 
-install:
-	install -Dm0755 target/$(RELEASE)/ion $(DESTDIR)/$(BINARY)
-
-uninstall:
-	rm $(DESTDIR)/$(BINARY)
+test.%:
+	TOOLCHAIN=$(TOOLCHAIN) bash tests/run_examples.sh $@
 
 vendor: $(VENDOR)
 
-version: $(GIT_REVISION)
-
-$(GIT_REVISION):
-	git rev-parse HEAD > git_revision.txt
-
 $(VENDOR):
 	rm -rf .cargo vendor vendor.tar.xz
 	mkdir -p .cargo

README.md

@@ -9,7 +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/html)
+[![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
@@ -24,21 +24,39 @@ yet to be written into the specification.
 
 # Ion Manual
 
-
-[The Ion manual online](https://doc.redox-os.org/ion-manual/html) 
+[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.
 
-You can build the manual using
+1. Build the documentation file for the builtins 
+
 ```sh
 make manual
-mdbook build -d ../public 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
@@ -54,26 +72,52 @@ 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.39.0` to set your Rust toolchain to the version that Ion is
+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.39.0 or higher is installed for your system.
+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.
 
-# Compile instructions for distribution
+# Installation 
+
+## Installation of Ion shell for one user 
 
 ```sh
 git clone https://gitlab.redox-os.org/redox-os/ion/
 cd ion
-RUSTUP=0 make # By default RUSTUP equals 1, which is for developmental purposes
-sudo make install prefix=/usr
+cargo install --path=. --force 
+```
+
+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
 ```
 
-> To compile in DEBUG mode, pass `DEBUG=1` as an argument to `make`
+# 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
 
@@ -98,3 +142,9 @@ For emacs users there is a [kindly-supported syntax highlighting plugin](https:/
 ```
 
 ![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/statement.rs

@@ -10,19 +10,15 @@ fn criterion_benchmark(c: &mut Criterion) {
         .copied()
         .batching(|lines| Terminator::new(lines).terminate())
         .collect::<Vec<_>>();
-    c.bench(
-        "statement-splitter-throughput",
-        ParameterizedBenchmark::new(
-            "statement",
-            |b, script| {
-                b.iter(|| {
-                    script.iter().flat_map(|cmd| StatementSplitter::new(cmd)).collect::<Vec<_>>()
-                })
-            },
-            vec![stmts],
-        )
-        .throughput(|script| Throughput::Bytes(script.len() as u64)),
-    );
+
+    let mut group = c.benchmark_group("statement_splitter_throughput");
+
+    group.throughput(Throughput::Bytes(stmts.len() as u64));
+    group.bench_function("statement_splitter", |b| {
+        b.iter(|| stmts.iter().flat_map(|cmd| StatementSplitter::new(cmd)).collect::<Vec<_>>())
+    });
+
+    group.finish();
 }
 
 criterion_group!(benches, criterion_benchmark);

clippy.toml

+cognitive-complexity-threshold = 100
+type-complexity-threshold = 1000

manual/README.md

@@ -8,3 +8,16 @@ which can be accessed at http://localhost:3000.
 At some point, Ion may provide a native builtin for quick access to reading the documentation
 of the shell, similarly to what Fish does with it's own documentation. This will require
 integrating **mdbook**'s library interface into Ion.
+
+
+## Buitin file
+
+The file under "manual/src/buitin.md" is created and updated via the command
+
+```
+make manual
+```
+
+Before opening/updating the mdbook, execute this command.
+Do not edit this file "manual/src/buitin.md" manually ! 
+

manual/book.toml

@@ -11,11 +11,13 @@ create-missing = false
 git-repository-url = "https://gitlab.redox-os.org/redox-os/ion"
 git-repository-icon = "fa-github"
 
-[output.linkcheck]
-# Should we check links on the internet? Enabling this option adds a
-# non-negligible performance impact
-follow-web-links = false
-
-# Are we allowed to link to files outside of the book's root directory? This
-# may help prevent linking to sensitive files (e.g. "../../../../etc/shadow")
-traverse-parent-directories = false
+# Disabled until issues can be fixed
+# [output.linkcheck]
+# # Should we check links on the internet? Enabling this option adds a
+# # non-negligible performance impact
+# follow-web-links = false
+# optional = true
+# 
+# # Are we allowed to link to files outside of the book's root directory? This
+# # may help prevent linking to sensitive files (e.g. "../../../../etc/shadow")
+# traverse-parent-directories = false

manual/src/SUMMARY.md

@@ -4,16 +4,9 @@
 
 - [Migrating from POSIX shells](migrating.md)
 
-- [Miscellaneous](misc/index.md)
+- [General rules](general.md)
 
-    - [Implicit `cd`](misc/01-implicitcd.md)
-    - [XDG App Directories](misc/02-xdg.md)
-    - [Quoting Rules](misc/03-quotation.md)
-    - [Multi-line Arguments](misc/04-multiargs.md)
-    - [Multi-line Strings](misc/05-multiline-strings.md)
-    - [Prompt Function](misc/06-prompt_fn.md)
-    - [Key Bindings](misc/07-keybindings.md)
-    - [General Tips](misc/08-general.md)
+- [Read–eval–print loop](repl.md)
 
 - [Variables](variables/00-variables.md)
 
@@ -32,6 +25,9 @@
     - [Brace Expansions](expansions/03-brace.md)
     - [Arithmetic Expansions](expansions/04-arithmetic.md)
     - [Method Expansions](expansions/05-method.md)
+    - [String Methods](expansions/06-stringmethods.md)
+    - [Array Methods](expansions/07-arraymethods.md)
+    - [Redox OS](expansions/08-redox-os.md)
 
 - [Slicing Syntax](slicing.md)
 
@@ -45,7 +41,9 @@
 
 - [Functions](functions.md)
 
-- [Script Executions](scripts.md)
+- [Script Executions](scripts/00-scripts.md)
+    - [Sourcing](scripts/01-sourcing_another_file.md)
+    - [Initialzing File](scripts/02-init_file.md)
 
 - [Signal Handling](signals.md)
 

manual/src/control/03-matches.md

@@ -46,10 +46,10 @@ Match guards can be added to a match to employ an additional test
 ```sh
 let foo = bar
 match $string
-    case _; echo "no match found"
     case "this" if eq $foo bar
         echo "this and foo = bar"
     case "this"
         echo "this and foo != bar"
+    case _; echo "no match found"
 end
 ```

manual/src/expansions/02-process.md

@@ -8,8 +8,14 @@ into an array delimited by whitespaces.
 
 ```sh
 let string = $(cmd args...)
-let array = @(cmd args...)
+let array = [ @(cmd args...) ]
 ```
 **NOTES:**
-- To split outputs by line, see `@lines($(cmd))`.
-- `@(cmd)` is equivalent to `@split($(cmd))`
+- To split outputs by line, see [@lines($(cmd))](https://doc.redox-os.org/ion-manual/html/expansions/05-method.html#lines).
+- `@(cmd)` is equivalent to [@split($(cmd))](https://doc.redox-os.org/ion-manual/html/expansions/05-method.html#split).
+```sh
+{{#include ../../../tests/process_exp.ion:process_expansion}}
+```
+```txt
+{{#include ../../../tests/process_exp.out:process_expansion}}
+```