Repository structure

README.md

@@ -1,6 +1,14 @@
 # The Move Book
 
-This is the repository for [the Move Book](https://move-book.com).
+This is the repository for [the Move Book](https://move-book.com) and [Move Language Reference](https://move-book.com/reference).
+
+## Structure
+
+- Two books are placed in the `book` and `reference` directories. The `book` directory contains the main book, and the `reference` directory contains the reference book.
+
+- The `theme` directory is linked to both books and contains the theme files, fonts and styles.
+
+- The `packages` directory contains the code samples used in both books.
 
 ## Archive
 

book.toml → book/book.toml

@@ -4,12 +4,12 @@ description = "First book about the Move programming language and the Move VM. M
 authors = ["Damir Shamanaev"]
 language = "en"
 multilingual = false
-src = "book"
-repository = "damirka/move-book"
+src = "src"
+repository = "MystenLabs/move-book"
 
 [build]
 build-dir = "build"
-extra-watch-dirs = ["packages"] # rebuild on Move Source changes
+extra-watch-dirs = ["../packages"] # rebuild on Move Source changes
 
 [output.html]
 additional-css = ["theme/css/custom.css"]

book/basic-syntax/address.md → book/src/basic-syntax/address.md

@@ -21,7 +21,7 @@ Links:
 To represent [addresses](./../concepts/address.md), Move uses a special type called `address`. It is a 32 byte value that can be used to represent any address on the blockchain. Addresses are used in two syntax forms: hexadecimal addresses prefixed with `0x` and named addresses.
 
 ```move
-{{#include ../../packages/samples/sources/basic-syntax/address.move:address_literal}}
+{{#include ../../../packages/samples/sources/basic-syntax/address.move:address_literal}}
 ```
 
 An address literal starts with the `@` symbol followed by a hexadecimal number or an identifier. The hexadecimal number is interpreted as a 32 byte value. The identifier is looked up in the [Move.toml](./../concepts/manifest.md) file and replaced with the corresponding address by the compiler. If the identifier is not found in the Move.toml file, the compiler will throw an error.
@@ -32,15 +32,15 @@ Sui Framework offers a set of helper functions to work with addresses. Given tha
 
 Example: Convert an address to a `u256` type and back.
 ```move
-{{#include ../../packages/samples/sources/basic-syntax/address.move:to_u256}}
+{{#include ../../../packages/samples/sources/basic-syntax/address.move:to_u256}}
 ```
 
 Example: Convert an address to a `vector<u8>` type and back.
 ```move
-{{#include ../../packages/samples/sources/basic-syntax/address.move:to_bytes}}
+{{#include ../../../packages/samples/sources/basic-syntax/address.move:to_bytes}}
 ```
 
 Example: Convert an address into a string.
 ```move
-{{#include ../../packages/samples/sources/basic-syntax/address.move:to_string}}
+{{#include ../../../packages/samples/sources/basic-syntax/address.move:to_string}}
 ```

book/basic-syntax/assert-and-abort.md → book/src/basic-syntax/assert-and-abort.md

@@ -29,7 +29,7 @@ A transaction can either succeed or fail. Successful execution applies all the c
 The `abort` keyword is used to abort the execution of a transaction. It is used in combination with an abort code, which will be returned to the caller of the transaction. The abort code is an integer of type `u64` and can be any value.
 
 ```move
-{{#include ../../packages/samples/sources/basic-syntax/assert-and-abort.move:abort}}
+{{#include ../../../packages/samples/sources/basic-syntax/assert-and-abort.move:abort}}
 ```
 
 The code above will, of course, abort with abort code `1`.
@@ -39,15 +39,15 @@ The code above will, of course, abort with abort code `1`.
 The `assert!` macro is a built-in macro that can be used to assert a condition. If the condition is false, the transaction will abort with the given abort code. The `assert!` macro is a convenient way to abort a transaction if a condition is not met. The macro shortens the code otherwise written with an `if` expression + `abort`.
 
 ```move
-{{#include ../../packages/samples/sources/basic-syntax/assert-and-abort.move:assert}}
+{{#include ../../../packages/samples/sources/basic-syntax/assert-and-abort.move:assert}}
 ```
 
 ## Error constants
 
 To make error codes more descriptive, it is a good practice to define error constants. Error constants are defined as `const` declarations and are usually prefixed with `E` followed by a camel case name. Error constants are no different from other constants and don't have special handling. So their addition is purely a practice for better code readability.
 
 ```move
-{{#include ../../packages/samples/sources/basic-syntax/assert-and-abort.move:error_const}}
+{{#include ../../../packages/samples/sources/basic-syntax/assert-and-abort.move:error_const}}
 ```
 
 ## Further reading

book/basic-syntax/comments.md → book/src/basic-syntax/comments.md

@@ -17,21 +17,21 @@ Comments are a way to add notes or document your code. They are ignored by the c
 ## Line comment
 
 ```Move
-{{#include ../../packages/samples/sources/basic-syntax/comments.move:line}}
+{{#include ../../../packages/samples/sources/basic-syntax/comments.move:line}}
 ```
 
 You can use double slash `//` to comment out the rest of the line. Everything after `//` will be ignored by the compiler.
 
 ```Move
-{{#include ../../packages/samples/sources/basic-syntax/comments.move:line_2}}
+{{#include ../../../packages/samples/sources/basic-syntax/comments.move:line_2}}
 ```
 
 ## Block comment
 
 Block comments are used to comment out a block of code. They start with `/*` and end with `*/`. Everything between `/*` and `*/` will be ignored by the compiler. You can use block comments to comment out a single line or multiple lines. You can even use them to comment out a part of a line.
 
 ```Move
-{{#include ../../packages/samples/sources/basic-syntax/comments.move:block}}
+{{#include ../../../packages/samples/sources/basic-syntax/comments.move:block}}
 ```
 
 This example is a bit extreme, but it shows how you can use block comments to comment out a part of a line.
@@ -41,7 +41,7 @@ This example is a bit extreme, but it shows how you can use block comments to co
 Documentation comments are special comments that are used to generate documentation for your code. They are similar to block comments, but they start with three slashes `///` and are placed before the definition of the item they document.
 
 ```Move
-{{#include ../../packages/samples/sources/basic-syntax/comments.move:doc}}
+{{#include ../../../packages/samples/sources/basic-syntax/comments.move:doc}}
 ```
 
 <!-- TODO: docgen, which members are in the documentation -->

book/basic-syntax/constants.md → book/src/basic-syntax/constants.md

@@ -21,15 +21,15 @@ Links:
 Constants are immutable values that are defined at the module level. They often serve as a way to give names to static values that are used throughout a module. For example, if there's a default price for a product, you might define a constant for it. Constants are stored in the module's bytecode, and each time they are used, the value is copied.
 
 ```move
-{{#include ../../packages/samples/sources/basic-syntax/constants.move:shop_price}}
+{{#include ../../../packages/samples/sources/basic-syntax/constants.move:shop_price}}
 ```
 
 ## Naming Convention
 
 Constants must start with a capital letter - this is enforced at the compiler level. For constants used as a value, there's a convention to use uppercase letters and underscores to separate words. It's a way to make constants stand out from other identifiers in the code. One exception is made for [error constants](./assert-and-abort.md#assert-and-abort), which are written in ECamelCase.
 
 ```move
-{{#include ../../packages/samples/sources/basic-syntax/constants.move:naming}}
+{{#include ../../../packages/samples/sources/basic-syntax/constants.move:naming}}
 ```
 
 ## Constants are Immutable
@@ -52,7 +52,7 @@ module book::immutable_constants {
 A common use case for an application is to define a set of constants that are used throughout the codebase. But due to constants being private to the module, they can't be accessed from other modules. One way to solve this is to define a "config" module that exports the constants.
 
 ```move
-{{#include ../../packages/samples/sources/basic-syntax/constants.move:config}}
+{{#include ../../../packages/samples/sources/basic-syntax/constants.move:config}}
 ```
 
 This way other modules can import and read the constants, and the update process is simplified. If the constants need to be changed, only the config module needs to be updated during the package upgrade.

book/basic-syntax/control-flow.md → book/src/basic-syntax/control-flow.md

@@ -40,13 +40,13 @@ if (<bool_expression>) <expression> else <expression>;
 Just like any other expression, `if` requires a semicolon, if there are other expressions following it. The `else` keyword is optional, except for the case when the resulting value is assigned to a variable. We will cover this below.
 
 ```move
-{{#include ../../packages/samples/sources/basic-syntax/control-flow.move:if_condition}}
+{{#include ../../../packages/samples/sources/basic-syntax/control-flow.move:if_condition}}
 ```
 
 Let's see how we can use `if` and `else` to assign a value to a variable:
 
 ```move
-{{#include ../../packages/samples/sources/basic-syntax/control-flow.move:if_else}}
+{{#include ../../../packages/samples/sources/basic-syntax/control-flow.move:if_else}}
 ```
 
 Here we assign the value of the `if` expression to the variable `y`. If `x` is greater than 0, `y` will be assigned the value 1, otherwise 0. The `else` block is necessary, because both branches must return a value of the same type. If we omit the `else` block, the compiler will throw an error.
@@ -74,15 +74,15 @@ while (<bool_expression>) { <expressions>; };
 Here is an example of a `while` loop with a very simple condition:
 
 ```move
-{{#include ../../packages/samples/sources/basic-syntax/control-flow.move:while_loop}}
+{{#include ../../../packages/samples/sources/basic-syntax/control-flow.move:while_loop}}
 ```
 
 ## Infinite `loop`
 
 Now let's imagine a scenario where the boolean expression is always `true`. For example, if we literally passed `true` to the `while` condition. As you might expect, this would create an infinite loop, and this is almost what the `loop` statement works like.
 
 ```move
-{{#include ../../packages/samples/sources/basic-syntax/control-flow.move:infinite_while}}
+{{#include ../../../packages/samples/sources/basic-syntax/control-flow.move:infinite_while}}
 ```
 
 An infinite `while`, or `while` without a condition, is a `loop`. The syntax for it is simple:
@@ -94,7 +94,7 @@ loop { <expressions>; };
 Let's rewrite the previous example using `loop` instead of `while`:
 
 ```move
-{{#include ../../packages/samples/sources/basic-syntax/control-flow.move:infinite_loop}}
+{{#include ../../../packages/samples/sources/basic-syntax/control-flow.move:infinite_loop}}
 ```
 
 <!-- TODO: that's a weak point lmao -->
@@ -114,7 +114,7 @@ break
 The `break` statement is used to stop the execution of a loop and exit it early. It is often used in combination with a conditional statement to exit the loop when a certain condition is met. To illustrate this point, let's turn the infinite `loop` from the previous example into something that looks and behaves more like a `while` loop:
 
 ```move
-{{#include ../../packages/samples/sources/basic-syntax/control-flow.move:break_loop}}
+{{#include ../../../packages/samples/sources/basic-syntax/control-flow.move:break_loop}}
 ```
 
 Almost identical to the `while` loop, right? The `break` statement is used to exit the loop when `x` is 5. If we remove the `break` statement, the loop will run forever, just like the previous example.
@@ -131,7 +131,7 @@ continue
 The example below skips odd numbers and prints only even numbers from 0 to 10:
 
 ```move
-{{#include ../../packages/samples/sources/basic-syntax/control-flow.move:continue_loop}}
+{{#include ../../../packages/samples/sources/basic-syntax/control-flow.move:continue_loop}}
 ```
 
 `break` and `continue` statements can be used in both `while` and `loop` loops.
@@ -147,7 +147,7 @@ return <expression>
 Here is an example of a function that returns a value when a certain condition is met:
 
 ```move
-{{#include ../../packages/samples/sources/basic-syntax/control-flow.move:return_statement}}
+{{#include ../../../packages/samples/sources/basic-syntax/control-flow.move:return_statement}}
 ```
 
 Unlike in other languages, the `return` statement is not required for the last expression in a function. The last expression in a function block is automatically returned. However, the `return` statement is useful when we want to exit a function early if a certain condition is met.

book/basic-syntax/copy-ability.md → book/src/basic-syntax/copy-ability.md

@@ -5,13 +5,13 @@ In Move, the *copy* ability on a type indicates that the instance or the value o
 However, Move type system allows you to define custom types with the *copy* ability.
 
 ```move
-{{#include ../../packages/samples/sources/basic-syntax/copy-ability.move:copyable}}
+{{#include ../../../packages/samples/sources/basic-syntax/copy-ability.move:copyable}}
 ```
 
 In the example above, we define a custom type `Copyable` with the *copy* ability. This means that instances of `Copyable` can be copied, both implicitly and explicitly.
 
 ```move
-{{#include ../../packages/samples/sources/basic-syntax/copy-ability.move:copyable_test}}
+{{#include ../../../packages/samples/sources/basic-syntax/copy-ability.move:copyable_test}}
 ```
 
 In the example above, `a` is copied to `b` implicitly, and then explicitly copied to `c` using the dereference operator. If `Copyable` did not have the *copy* ability, the code would not compile, and the Move compiler would raise an error.
@@ -21,7 +21,7 @@ In the example above, `a` is copied to `b` implicitly, and then explicitly copie
 The `copy` ability is closely related to [`drop` ability](./drop-ability.md). If a type has the *copy* ability, very likely that it should have `drop` too. This is because the *drop* ability is required to clean up the resources when the instance is no longer needed. If a type has only *copy*, then managing its instances gets more complicated, as the values cannot be ignored.
 
 ```move
-{{#include ../../packages/samples/sources/basic-syntax/copy-ability.move:copy_drop}}
+{{#include ../../../packages/samples/sources/basic-syntax/copy-ability.move:copy_drop}}
 ```
 
 All of the primitive types in Move behave as if they have the *copy* and *drop* abilities. This means that they can be copied and dropped, and the Move compiler will handle the memory management for them.

book/basic-syntax/drop-ability.md → book/src/basic-syntax/drop-ability.md

@@ -50,7 +50,7 @@ A struct without abilities cannot be discarded, or copied, or stored in the stor
 The `drop` ability - the simplest of them - allows the instance of a struct to be *ignored* or *discarded*. In many programming languages this behavior is considered default. However, in Move, a struct without the `drop` ability is not allowed to be ignored. This is a safety feature of the Move language, which ensures that all assets are properly handled. An attempt to ignore a struct without the `drop` ability will result in a compilation error.
 
 ```move
-{{#include ../../packages/samples/sources/basic-syntax/drop-ability.move:main}}
+{{#include ../../../packages/samples/sources/basic-syntax/drop-ability.move:main}}
 ```
 
 The `drop` ability is often used on custom collection types to eliminate the need for special handling of the collection when it is no longer needed. For example, a `vector` type has the `drop` ability, which allows the vector to be ignored when it is no longer needed. However, the biggest feature of Move's type system is the ability to not have `drop`. This ensures that the assets are properly handled and not ignored.

book/basic-syntax/expression.md → book/src/basic-syntax/expression.md

@@ -15,37 +15,37 @@ In the [Primitive Types](./primitive-types.md) section, we introduced the basic
 - `x"0A"` HEX literal for byte values
 
 ```move
-{{#include ../../packages/samples/sources/basic-syntax/expression.move:literals}}
+{{#include ../../../packages/samples/sources/basic-syntax/expression.move:literals}}
 ```
 
 ## Operators
 
 Ariphmetic, logical, and bitwise operators are used to perform operations on values. The result of an operation is a value, so operators are also expressions.
 
 ```move
-{{#include ../../packages/samples/sources/basic-syntax/expression.move:operators}}
+{{#include ../../../packages/samples/sources/basic-syntax/expression.move:operators}}
 ```
 
 ## Blocks
 
 A block is a sequence of statements and expressions, and it returns the value of the last expression in the block. A block is written as a pair of curly braces `{}`. A block is an expression, so it can be used anywhere an expression is expected.
 
 ```move
-{{#include ../../packages/samples/sources/basic-syntax/expression.move:block}}
+{{#include ../../../packages/samples/sources/basic-syntax/expression.move:block}}
 ```
 
 ## Function Calls
 
 We go into detail about functions in the [Functions](./functions.md) section. However, we already used function calls in the previous sections, so it's worth mentioning them here. A function call is an expression that calls a function and returns the value of the last expression in the function body.
 
 ```move
-{{#include ../../packages/samples/sources/basic-syntax/expression.move:fun_call}}
+{{#include ../../../packages/samples/sources/basic-syntax/expression.move:fun_call}}
 ```
 
 ## Control Flow Expressions
 
 Control flow expressions are used to control the flow of the program. They are also expressions, so they return a value. We cover control flow expressions in the [Control Flow](./control-flow.md) section. Here's a very brief overview:
 
 ```move
-{{#include ../../packages/samples/sources/basic-syntax/expression.move:control_flow}}
+{{#include ../../../packages/samples/sources/basic-syntax/expression.move:control_flow}}
 ```