Fix broken links

book.toml

@@ -10,3 +10,62 @@ default-theme = "navy"
 site-url = "/manual/"
 git-repository-url = "https://github.com/braneframework/manual"
 git-repository-icon = "fa-github"
+
+[preprocessor.variables.variables]
+specification_root = "https://braneframework.github.io/specification"
+brane_docs_root = "https://braneframework.github.io/brane/unstable"
+
+
+[output.linkcheck]
+# Should we check links on the internet? Enabling this option adds a
+# non-negligible performance impact
+follow-web-links = 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
+
+# If necessary, you can exclude one or more links from being checked with a
+# list of regular expressions. The regex will be applied to the link href (i.e.
+# the `./index.html` in `[some page](./index.html)`) so it can be used to
+# ignore both web and filesystem links.
+#
+# Hint: you can use TOML's raw strings (single quote) to avoid needing to
+# escape things twice.
+exclude = [ 'TODO', 'https://flaticon.com' ]
+
+# The User-Agent to use when sending web requests
+user-agent = "mdbook-linkcheck-0.4.0"
+
+# The number of seconds a cached result is valid for (12 hrs by default)
+cache-timeout = 43200
+
+# How should warnings be treated?
+#
+# - "warn" will emit warning messages
+# - "error" treats all warnings as errors, failing the linkcheck
+# - "ignore" will ignore warnings, suppressing diagnostic messages and allowing
+#   the linkcheck to continuing
+warning-policy = "warn"
+
+# Extra HTTP headers that must be send to certain web sites
+# in order to link check to succeed.
+#
+# This is a dictionary (map), with keys being regexes
+# matching a set of web sites, and values being an array of
+# the headers.
+[output.linkcheck.http-headers]
+# Any hyperlink that contains this regexp will be sent
+# the "Accept: text/html" header
+# 'crates\.io' = ["Accept: text/html"]
+
+# mdbook-linkcheck will interpolate environment variables into your header via
+# $IDENT.
+#
+# If this is not what you want you must escape the `$` symbol, like `\$TOKEN`.
+# `\` itself can also be escaped via `\\`.
+#
+# Note: If interpolation fails, the header will be skipped and the failure will
+# be logged. This can be useful if a particular header isn't always necessary,
+# but may be helpful (e.g. when working with rate limiting).
+# 'website\.com' = ["Authorization: Basic $TOKEN"]

src/SUMMARY.md

@@ -46,10 +46,6 @@
   - [Variables](./scientists/bscript/variables.md)
   - [Control flow](./scientists/bscript/control-flow.md)
   - [Datasets in a workflow](./scientists/bscript/datasets.md)
-<!-- - [Bakery Workflows](./scientists/bakery/introduction.md)
-  - [Your first workflow](./scientists/bakery/workflow.md)
-  - [Workflows and Data](./scientists/bakery/workflows-data.md)
-  - [Advanced workflows](./scientists/bakery/advanced-workflows.md) -->
 - [Using the Brane-IDE](./scientists/jupyter.md)
 
 
@@ -74,6 +70,7 @@
 # Packages
 - [Introduction](./packages/introduction.md)
 - [`container.yml` documentation](./packages/container_yml.md)
+- [Executable code unit](./packages/ecu.md)
 
 
 # BraneScript

src/before-reading.md

@@ -21,4 +21,4 @@ Looked at from the highest level of abstraction, Brane has a client part (in the
 ## Where next
 To continue reading, we suggest you start at the first chapter for your role. You can select it in the sidebar to the left.
 
-If you are part of the fifth, "hidden" role (the Brane administrators), you have [your own book](/admins); we recommend you continue there. It also details how to obtain, compile and run the framework for testing purposes.
+If you are part of the fifth, "hidden" role (the Brane developers), you have [your own book]({{ specification_root }}); we recommend you continue there. It also details how to obtain, compile and run the framework for testing purposes.

src/branescript/advanced.md

@@ -160,4 +160,4 @@ Note that there are a few peculiarities about parallel statements:
   println(res);
   ```
   which will print `84`.
-  > <img src="../../assets/img/info.png" alt="info" width="16" style="margin-top: 3px; margin-bottom: -3px"/> For a complete overview of all merge strategies, check the [BraneScript documentation](../../branescript/statements.md).
+  > <img src="../../assets/img/info.png" alt="info" width="16" style="margin-top: 3px; margin-bottom: -3px"/> For a complete overview of all merge strategies, check the [BraneScript documentation]({{ specification_root }}/appendix/languages/bscript/features.html#parallel-statements).

src/branescript/basics.md

@@ -1,5 +1,5 @@
 # Basic concepts
-In the [previous chapter](./workflow.md), we discussed your first "Hello, world!"-workflow. In this chapter, we will extend upon this, and go over the basic language features of BraneScript. We will talk about things like variables, if-statements and loops, parallel statements and builtin-functions.
+In the [previous chapter](./hello-world.md), we discussed your first "Hello, world!"-workflow. In this chapter, we will extend upon this, and go over the basic language features of BraneScript. We will talk about things like variables, if-statements and loops, parallel statements and builtin-functions.
 
 More complex features, such as arrays, function definitions, classes or Data and IntermediateResults, are left to the next few chapters.
 
@@ -17,7 +17,7 @@ So, how can we use this? The first step is to declare a new variable, to make Br
 ```bscript
 let <ID> := <EXPR>;
 ```
-where `<ID>` is some identifier that you want to use for your variable (existing only of alphanumeric characters and an underscore, `_`), and `<EXPR>` is some code that _evaluates_ to a certain value. We've already seen an example of this: a function call is an expression, since it has a return value that we can pass to other functions or statements. Other expressions include _literal values_ (e.g., `true`, `42`, `3.14` or `"Hello, there!"`) or logical or mathmatical operations (e.g., addition, subtraction, logical conjunction, comparison, etc). For some more examples, see [below](#arrays), or check the [BraneScript documentation](../../branescript/expressions.md) for a full overview.
+where `<ID>` is some identifier that you want to use for your variable (existing only of alphanumeric characters and an underscore, `_`), and `<EXPR>` is some code that _evaluates_ to a certain value. We've already seen an example of this: a function call is an expression, since it has a return value that we can pass to other functions or statements. Other expressions include _literal values_ (e.g., `true`, `42`, `3.14` or `"Hello, there!"`) or logical or mathmatical operations (e.g., addition, subtraction, logical conjunction, comparison, etc). For some more examples, see [below](#arrays), or check the [BraneScript documentation]({{ specification_root }}/appendix/languages/bscript/features.html#expressions) for a full overview.
 
 Yet another example of an expression is a _variable reference_, which effectively reads a particular variable. To use it, simply specify the identifier of the variable you declared (`ID`) any time you can use an expression. For example:
 ```bscript
@@ -57,7 +57,7 @@ foo := foo * 2;
 
 
 ## Functions
-Something that you've already seen used in the [previous chapter](./workflow.md) and the previous section, is the use of _function calls_.
+Something that you've already seen used in the [previous chapter](./hello-world.md) and the previous section, is the use of _function calls_.
 
 This concept is used in almost any language, and essentially represents a temporary jump to some other part of code that is executed, and then the program continues from the function call onwards. Crucially, we typically allow these snippets to take in some values - _arguments_ - and hand us back a value when they are done - a _return value_.
 
@@ -82,14 +82,14 @@ let fourty_two := add(add(add(2, add(zero(), 20)), zero()), 20);
 println(fourty_two);   // Should print '42'
 ```
 
-Note that BraneScript uses the same syntax for calling imported functions (see the [previous chapter](./workflow.md) with the `hello_world()`-function), builtin functions (think `println()`; see [below](#builtin-functions)) and defined functions (check the [relevant chapter](./funcs-classes.md)).
+Note that BraneScript uses the same syntax for calling imported functions (see the [previous chapter](./hello-world.md) with the `hello_world()`-function), builtin functions (think `println()`; see [below](#builtin-functions)) and defined functions (check the [relevant chapter](./funcs-classes.md)).
 
 To be complete, you can import all of the functions within a package using the import-statement:
 ```bscript
 import <id>;
 ```
 
-You've already seen examples of this in the [previous chapter](./workflow.md).
+You've already seen examples of this in the [previous chapter](./hello-world.md).
 
 
 ## Control flow
@@ -336,4 +336,4 @@ If you have the idea you understand these basic constructs a little, congratulat
 
 In the [next chapter](./funcs-classes.md), we examine how to define functions and classes and how to use the latter. Then, in the [chapter after that](./data-results.md), we examine BraneScript's builtin `Data`-class, which is integral to writing useful workflows. Finally, in the [last chapter](./advanced.md) of the BraneScript-part, we discuss some of the finer details of BraneScript as a language.
 
-Separate from these introductory chapters, there is also the complete and more formal overview of the language in the [BraneScript documentation](../../branescript/introduction.md). Those chapters should cover all of its details, and function as useful reference material once you've grasped the basics.
+Separate from these introductory chapters, there is also the complete and more formal overview of the language in the [BraneScript documentation]({{ specification_root }}/appendix/languages/bscript/introduction.html). Those chapters should cover all of its details, and function as useful reference material once you've grasped the basics.

src/branescript/hello-world.md

@@ -15,7 +15,7 @@ Next, it is good practise to write a header comment to explain what a file does.
 // A BraneScript workflow for printing "Hello, world!" to the screen.
 ```
 
-Next, we have to tell the Brane system which packages we want to use in our workflow. To do so, we will use the [`import`](../../branescript/statements.md#imports)-statement. This statement takes the identifier if the package, followed by a semicolon (`;`).
+Next, we have to tell the Brane system which packages we want to use in our workflow. To do so, we will use the [`import`]({{ specification_root }}/appendix/languages/bscript/features.html#import-statements)-statement. This statement takes the identifier if the package, followed by a semicolon (`;`).
 
 > <img src="../../assets/img/info.png" alt="info" width="16" style="margin-top: 3px; margin-bottom: -3px"/> Note that all Brane statements end with a semicolon `;`. If you forget it, you may encounter weird syntax errors; so if you don't know what the error means but it's a syntax error, you should first check for proper usage of the semicolons.
 
@@ -25,13 +25,13 @@ We want to import the `hello_world` package, so we add:
 
 import hello_world;
 ```
-This will import _all_ of the package's functions into the global namespace. Be aware of this, since this may lead to naming conflicts. See the [advanced workflows](./advanced-workflows.md#scoping)-chapter for ways of dealing with this.
+This will import _all_ of the package's functions into the global namespace. Be aware of this, since this may lead to naming conflicts. See the [advanced workflows](./advanced.md#scoping)-chapter for ways of dealing with this.
 
-In our case, this imports only one function: the `hello_world()` function. As you can read in the [package's README](https://github.com/epi-project/brane-std/tree/main/hello_world), this function takes no arguments, but returns a string who's value is: `Hello, world!`.
+In our case, this imports only one function: the `hello_world()` function. As you can read in the [package's README](https://github.com/braneframework/brane-std/tree/main/hello_world), this function takes no arguments, but returns a string who's value is: `Hello, world!`.
 
 > <img src="../../assets/img/info.png" alt="info" width="16" style="margin-top: 3px; margin-bottom: -3px"/> If you do not want to go to the internet to find out what a package does, you can also use the `inspect`-subcommand of the `brane`-executable:
 > ```bash
-> brane inspect hello_world
+> brane package inspect hello_world
 > ```
 > which will print something like:
 > <img src="../../assets/img/workflow-inspect.png" alt="Details about the 'hello_world' package."/>
@@ -52,7 +52,7 @@ However, running the file like this will probably not work. Remember that the pa
 // (as you would in other languages)
 println(hello_world());
 ```
-See the [BraneScript documentation](../../branescript/builtins.md) for a full overview of all supported builtins.
+See the [BraneScript documentation](TODO) for a full overview of all supported builtins.
 
 We now have a workflow that should print `Hello, world!` when we run it, which is what we set out to do!
 
@@ -74,7 +74,7 @@ Be sure to save it somewhere where you can find it. Remember, we will refer to i
 
 
 ## Running a workflow
-After you have written a workflow file, you can run it using the `brane` executable. Thus, make sure you have it installed and available in your PATH (see the [installation](../installation.md) chapter).
+After you have written a workflow file, you can run it using the `brane` executable. Thus, make sure you have it installed and available in your PATH (see the [installation](../scientists/installation.md) chapter).
 
 There are two modes of running a workflow: you can run it locally, in which all tasks are executed on your own machine and using the packages that are available locally. Alternatively, you can also run it on a remote instance, in which the tasks are executed on domains and nodes within that instance, using packages available only in that instance.
 
@@ -83,13 +83,12 @@ Typically, you test your workflow locally first to make sure that it works and c
 
 To run it locally, you first have to make sure you have all the packages available locally. For us, this is the `hello_world` package. You can check whether you have it by running `brane list`, and then install it if you don't by downloading it from GitHub:
 ```bash
-brane import epi-project/brane-std hello_world
+brane package import braneframework/brane-std hello_world
 ```
-For more details on this, see the [previous chapter](../packages.md).
 
-With the packages in place, you can then use the `brane run`-command to run the file we have just created:
+With the packages in place, you can then use the `brane workflow run`-command to run the file we have just created:
 ```bash
-brane run hello_world.bs
+brane workflow run hello_world.bs
 ```
 (Replace `hello_world.bs` with the path to the file you have created)
 
@@ -104,17 +103,17 @@ If your workflow failed, Brane will try to offer you as much help as it can. Mak
 ### Remote execution
 The procedure for executing a workflow on a remote instance is very comparable to running a workflow locally.
 
-The first step is to make sure that the instance has all the packages you need. Use a combination of `brane search` and `brane push` to achieve this (see the [previous chapter](../packages.md) for more information).
+The first step is to make sure that the instance has all the packages you need. Use a combination of `brane search` and `brane push` to achieve this.
 
 Then, to execute your workflow, you can do the same, but now specify the `--remote` flag to use the instance currently selected:
 ```bash
-brane run --remote ...
+brane workflow run --remote ...
 ```
 
 Thus, to run our workflow on the remote instance we are currently loggin-in to, we would use to the following command:
 ```bash
 # We assume your already executed 'brane instance add'
-brane run --remote hello_world.bs
+brane workflow run --remote hello_world.bs
 ```
 
 If your packages are in order, this should produce the same result as when executing the workflow locally.
@@ -123,13 +122,13 @@ If your packages are in order, this should produce the same result as when execu
 ## The REPL
 As an alternative to writing an entire file and running that, you can also use the Brane Read-Eval-Print Loop (REPL). This is an interactive environment that you can use to provide workflows in a segmented way, typically providing one statement at a time and seeing the result immediately.
 
-> <img src="../../assets/img/warning.png" alt="warning" width="16" style="margin-top: 3px; margin-bottom: -3px"/> The REPL works in most cases, but it is known to be buggy for some design patterns (see subsequent chapters). If you run into an issue where something works in a file but not in a REPL, you can typically solve it by writing the separate statements in a single line. Please also let us know by [raising an issue](https://github.com/epi-project/brane/issues).
+> <img src="../../assets/img/warning.png" alt="warning" width="16" style="margin-top: 3px; margin-bottom: -3px"/> The REPL works in most cases, but it is known to be buggy for some design patterns (see subsequent chapters). If you run into an issue where something works in a file but not in a REPL, you can typically solve it by writing the separate statements in a single line. Please also let us know by [raising an issue](https://github.com/BraneFramework/brane/issues).
 
 Because our workflow is so short, we will re-do it in the REPL.
 
 First, open it by running:
 ```bash
-brane repl
+brane workflow repl
 ```
 This should welcome you with the following:
 
@@ -149,14 +148,14 @@ which should produce:
 
 Which is the same result as with the separate file, instead that we've now interleaved writing and executing the workflow.
 
-You can also use the REPL in a remote scenario, by providing the `--remote` option when running it, similar to `brane run`:
+You can also use the REPL in a remote scenario, by providing the `--remote` option when running it, similar to `brane workflow run`:
 ```bash
-brane repl --remote
+brane workflow repl --remote
 ```
 Every command executed in this REPL is executed on the specified instance.
 
 > <img src="../../assets/img/info.png" alt="info" width="16" style="margin-top: 3px; margin-bottom: -3px"> In principle, executing the same workflow as a file or in the REPL as separate statements should give you the same result. Unfortunately, in the context of Brane, this might not hold true depending on the policies present in an instance. For example, some policies may want to have gaurantees about what happens in the next step of workflow, which is impossible for Brane to provide if it's executing the statements one-by-one. Thus, you can typically expect your workflow to be authorized more easily if it's running in one go as a file.
 
 
 ## Next
-In the [next chapter](./workflows-data.md), we will treat datasets and intermediate results, which are an essential component to writing workflows. If you are already familiar with those, you can also check the [subsequent chapter](./advanced-workflows.md), which introduces the finer concepts of workflow writing. Alternatively, you can also checkout the full [BraneScript documentation](../branescript/introduction.md).
+In an [upcoming chapter](./data-results.md), we will treat datasets and intermediate results, which are an essential component to writing workflows. If you are already familiar with those, you can also check the [subsequent chapter](./advanced.md), which introduces the finer concepts of workflow writing. Alternatively, you can also checkout the full [BraneScript documentation](../branescript/introduction.md).