refactor: fix sections and subsections

src/additional-information.md

@@ -6,14 +6,14 @@ More information about the Flix programming language can be found in:
   language researchers.
 - A series of [blog posts](./blog-posts.md) written by the community.
 
-### Getting Help
+## Getting Help
 
 If you have a question or comment we are happy to help you out on our Gitter
 channel:
 
 [https://gitter.im/flix/Lobby](https://gitter.im/flix/Lobby)
 
-### Reporting a Bug
+## Reporting a Bug
 
 If you encounter a bug, you can report it here:
 

src/applicative-for-yield.md

@@ -1,11 +1,11 @@
-## Applicative For-Yield
+# Applicative For-Yield
 
 In addition to the monadic `forM` expression, Flix supports an applicative
 `forA` expression that builds on the `Applicative` trait. The `forA`
 construct makes it simple to write error-handling code which uses the
 `Validation[e, t]` data type. 
 
-### Working with Validations
+## Working with Validations
 
 We can use the `forA` expression to validate user input while collecting all
 errors.
@@ -61,7 +61,7 @@ evaluates to:
 Success(Connection(luckyluke, password12356789))
 ```
 
-### Applicatives are Independent Computations
+## Applicatives are Independent Computations
 
 We can write a monadic `forM` expression where the result of one monadic
 operation is used as the input to another monadic operation. For example:
@@ -96,7 +96,7 @@ then the Flix compiler emits a compiler error:
 because the computations of `x` and `y` are _independent_ and hence the value of
 `x` is _not_ in scope when we define the value of `y`.
 
-### Desugaring
+## Desugaring
 
 The `forA` expression is syntactic sugar for uses of `Functor.map` and
 `Applicative.ap`.

src/arrays.md

@@ -1,4 +1,4 @@
-## Arrays
+# Arrays
 
 Flix supports mutable _scoped_ arrays. An array is a fixed-length mutable
 sequence of elements that share the same type. Arrays are laid out consecutively
@@ -26,7 +26,7 @@ recommend that arrays are used sparingly. Instead, we recommend using the
 
 > **Hint:** Use `MutList` if you need a _growable_ mutable sequence of elements.
 
-### Array Literals
+## Array Literals
 
 The syntax of an array literal is of the form `Array#{e1, e2, e3, ...} @ r`
 where `e1`, `e2`, and so forth are _element expressions_, and `r` is the _region
@@ -46,7 +46,7 @@ refer to the chapter on [Regions](regions.md).
 
 Running the program prints `Array#{"Apple", "Pear", "Mango"}`.
 
-### Allocating Arrays
+## Allocating Arrays
 
 We can allocate an array of size `n` filled with the same element using the
 `Array.repeat` function. For example:
@@ -84,7 +84,7 @@ region rc {
 Note that we must pass the region `rc` as an argument to `List.toArray` since
 the function must know to which region the returned array should belong.
 
-### Allocating Arrays with Uninitialized Elements
+## Allocating Arrays with Uninitialized Elements
 
 We can use the `Array.empty` function to create an array of a given length where
 the content of the array is uninitialized. For example:
@@ -110,7 +110,7 @@ Flix does not have a `null` value, but one can be indirectly introduced by
 reading from improperly initialized arrays which can lead to
 `NullPointerException`s.
 
-### Reading from and Writing to Arrays
+## Reading from and Writing to Arrays
 
 We can retrieve or update the element at a specific position in an array using
 `Array.get` and `Array.put`, respectively. For example:
@@ -141,7 +141,7 @@ let strings =
     Array.put("World", 1);
 ```
 
-### Slicing Arrays
+## Slicing Arrays
 
 We can slice arrays using `Array.slice`. A slice of an array is a new (shallow)
 copy of a sub-range of the original array. For example
@@ -156,7 +156,7 @@ region rc {
 
 which prints `Array#{"Pear"}` when run.
 
-### Taking the Length of an Array
+## Taking the Length of an Array
 
 We can compute the length of an array using the `Array.length` function. For
 example
@@ -174,7 +174,7 @@ which prints `3` when run.
 > we recommend to use functions such as `Array.count`, `Array.forEach`, and
 > `Array.transform`.
 
-### Additional Array Operations
+## Additional Array Operations
 
 The `Array` module offers an extensive collection of functions for working with
 arrays. For example, `Array.append`, `Array.copyOfRange`, `Array.findLeft`,

src/associated-effects.md

@@ -1,4 +1,4 @@
-## Associated Effects
+# Associated Effects
 
 We have seen how associated types increase the flexibility of traits by allowing
 each instance to specify concrete types for the associated types. Associated
@@ -84,7 +84,7 @@ instance Dividable[Int32] {
 }
 ```
 
-### Associated Effects and Regions
+## Associated Effects and Regions
 
 We often want to use associated effects in combination with regions.
 

src/associated-types.md

@@ -1,4 +1,4 @@
-## Associated Types
+# Associated Types
 
 An associated type is a type member of a trait that is specified by each trait
 instance. Associated types are often considered a more natural alternative to
@@ -104,7 +104,7 @@ If we had such overlapping instances, an expression like `Addable.add(Set#{},
 Set#{})` would become ambiguous: Are we adding two sets? Or are we adding the
 empty set to a set? 
 
-### Example: A `ForEach` Trait
+## Example: A `ForEach` Trait
 
 We can use associated types to define a trait for collections that have a
 `forEach` function: 
@@ -152,7 +152,7 @@ instance ForEach[String] {
 }
 ```
 
-### Example: A `Collection` Trait
+## Example: A `Collection` Trait
 
 As another example, we can define a trait for collections:
 
@@ -190,7 +190,7 @@ instance Collection[Set[a]] with Order[a] {
 }
 ```
 
-### Equality Constraints
+## Equality Constraints
 
 We sometimes want to write polymorphic functions where we _restrict_ an
 associated type. 
@@ -211,7 +211,7 @@ Specifically, the equality constraint `Collection.Elm[t] ~ Int32` assert that
 This restriction ensures that the elements of the collection are integers and
 allows us to call `List.sum`.
 
-### Default Types
+## Default Types
 
 We can define a default type for an associated type.
 

src/automatic-derivation.md

@@ -1,4 +1,4 @@
-## Automatic Derivation
+# Automatic Derivation
 
 Flix supports automatic derivation of several traits, including:
 
@@ -8,7 +8,7 @@ Flix supports automatic derivation of several traits, including:
 - `Sendable` — to enable the values of an (immutable) type to be sent over a channel.
 - `Coerce` - to convert simple data types to their underlying representation.
 
-### Derivation of Eq and Order
+## Derivation of Eq and Order
 
 We can automatically derive instances of the `Eq` and `Order` traits using
 the `with` clause in the `enum` declaration. For example: 
@@ -35,7 +35,7 @@ def main(): Unit \ IO =
 > **Note**: Automatic derivation of `Eq` and `Order` requires that the inner
 > types of the `enum` implement `Eq` and `Order` themselves.
 
-### Derivation of ToString
+## Derivation of ToString
 
 We can also automatically derive `ToString` instances:
 
@@ -63,7 +63,7 @@ which prints:
 A Circle(123), Square(123), and Rectangle(123, 456) walk into a bar.
 ```
 
-### Derivation of Sendable
+## Derivation of Sendable
 
 We can automatically derive implementations of the `Sendable` trait (which
 allow values of a specific type to be sent over a channel). For example:
@@ -106,7 +106,7 @@ Because it takes a type parameter of kind 'Region'.
 
 This is because mutable data is not safe to share between threads.
 
-### Derivation of Coerce
+## Derivation of Coerce
 
 We can automatically derive implementations of the `Coerce` trait.
 The `Coerce` trait converts a simple (one-case) data type

src/blog-posts.md

@@ -1,4 +1,4 @@
-## Blog Posts
+# Blog Posts
 
 A few people are writing about various aspects of Flix on their blogs:
 

src/boxing-and-unboxing.md

@@ -1,11 +1,11 @@
-## Boxing and Unboxing
+# Boxing and Unboxing
 
 Unlike Java, Flix never performs implicit boxing or unboxing of values. 
 
 We believe auto boxing is a design flaw and do not plan to support it. Hence,
 primitive values must be manually boxed and unboxed. 
 
-### Boxing
+## Boxing
 
 The following example shows how to box a primitive integer:
 
@@ -19,7 +19,7 @@ Here the call to `Box.box(x)` returns an `Integer` object. Since `i` is an
 object, we can call `toString` on it. Boxing is a pure operation, but calling
 `toString` has the `IO` effect. 
 
-### Unboxing
+## Unboxing
 
 The following example shows how to unbox two Java `Integer` objects:
 

src/bug-and-unreachable.md

@@ -1,4 +1,4 @@
-## `bug!` and `unreachable!`
+# `bug!` and `unreachable!`
 
 Flix supports two special "functions": `bug!` and
 `unreachable!` that can be used to indicate when an

src/build.md

@@ -1,9 +1,9 @@
-## Build Management
+# Build Management
 
 We now discuss the build commands. Each command can be executed from the command
 line, from the REPL, and from VSCode. 
 
-### Creating a New Project
+## Creating a New Project
 
 We can create a new project, inside a directory, with the `init` command. 
 
@@ -30,13 +30,13 @@ The `flix.toml` manifest file is discussed in the next section.
 > **Tip:** The `init` command is safe to use; it will only create files that do
 > not already exist. 
 
-### Checking a Project
+## Checking a Project
 
 We can check a project for compiler errors with the `check` command. During
 development, the `check` command is preferable to the `build` command because it
 skips code generation (and hence is significantly faster). 
 
-### Building a Project
+## Building a Project
 
 We can compile a project with the `build` command. Running the `build` command
 will compile the entire project and emit bytecode, i.e. compiled Java classes,
@@ -45,7 +45,7 @@ to the `build` directory.
 Flix has no `clean` command. Deleting the `build` directory serves the same
 purpose.
 
-### Building a JAR-file
+## Building a JAR-file
 
 We can compile a project to a JAR-file with the `build-jar` command. The
 `build-jar` command emits a `artifact/project.jar` file. If there is `main`
@@ -61,7 +61,7 @@ on JAR-files.
 
 > **Note:** `build-jar` automatically invokes the `build` command.
 
-### Building a fat JAR-file (bundling all dependencies)
+## Building a fat JAR-file (bundling all dependencies)
 
 We can compile a project to a single standalone fat JAR-file with the
 `build-fatjar` command. The `build-fatjar` command emits a
@@ -74,7 +74,7 @@ directory.
 
 > **Note:** `build-fatjar` automatically invokes the `build` command.
 
-### Building a Flix Project
+## Building a Flix Project
 
 We can bundle a project into a Flix package file (fpkg) with the `build-pkg`
 command. Running the `build-pkg` command emits a `artifact/project.fpkg` file.
@@ -83,12 +83,12 @@ A Flix package file (fpkg) is essentially zip-file of the project source code. A
 Flix package, together with its `flix.toml` manifest, can be published on
 GitHub.
 
-### Running a Project
+## Running a Project
 
 We do not have to build a JAR-file to run a project, we can simply use the `run`
 command which will compile and run the main entry point.
 
-### Testing a Project
+## Testing a Project
 
 We can use the `test` command to run all test cases in a project. Flix will
 collect all functions marked with `@Test`, execute them, and print a summary of

src/calling-methods.md

@@ -1,4 +1,4 @@
-## Calling Object Methods
+# Calling Object Methods
 
 In Flix, we can call methods on Java objects using syntax similar to Java.
 

src/chains-and-vectors.md

@@ -1,4 +1,4 @@
-## Chains and Vectors
+# Chains and Vectors
 
 In addition to immutable `List`s, Flix also supports immutable `Chain`s and
 `Vector`s. 
@@ -23,7 +23,7 @@ When to use `List`, `Chain`, or `Vector`?:
 - The `Chain` data structure is more rarely used, but shines when fast appends
   are required. 
 
-### Chains
+## Chains
 
 A `Chain[t]` is an immutable linked sequence of elements. 
 
@@ -53,7 +53,7 @@ println(c)
 
 which prints `Chain#{1}` when compiled and executed.
 
-### Vectors
+## Vectors
 
 A `Vector[t]` is an immutable fixed-length sequence of contiguous elements of
 type `t`.

src/checked-casts.md

@@ -1,4 +1,4 @@
-## Checked Type and Effect Casts
+# Checked Type and Effect Casts
 
 The Flix type and effect system – by design – does not support sub-typing nor
 sub-effecting. To work around these limitations, which are rare in practice,
@@ -11,7 +11,7 @@ Flix has two _safe_ upcast constructs:
 > be _safe_. The Flix compiler will check at compile-time that every checked
 > cast cannot go wrong. 
 
-### Checked Type Casts
+## Checked Type Casts
 
 The following program:
 
@@ -56,7 +56,7 @@ let _: ##java.lang.Object       = checked_cast(null);
 let _: ##java.lang.String       = checked_cast(null);
 ```
 
-### Checked Effect Casts
+## Checked Effect Casts
 
 The following program:
 
@@ -102,7 +102,7 @@ The `checked_ecast` construct allows us to pretend that `x + 1` has the `IO` eff
 > require their function arguments to have a specific effect. Instead they
 > should be effect polymorphic. 
 
-### Function Types
+## Function Types
 
 Neither the `checked_cast` nor the `checked_ecast` constructs work on function types.