Update all titles + various improvements (cairo-book#726)

Author: TAdev0

cairo-documentation-style-guide.md

@@ -39,15 +39,15 @@ The style guide is based on the best practices collected from the following book
 - [Terminology](#terminology)
   - [Recommended Terms](#recommended-terms)
 - [Admonitions](#admonitions)
-- [Appendix A Existing Style Guides](#appendix-a-existing-style-guides)
+- [Appendix A: Existing Style Guides](#appendix-a-existing-style-guides)
   - [Documentation](#documentation)
   - [Code](#code)
 
 ## Heading Titles
 
 The Cairo Book usually have heading titles based on nouns or gerunds:
 
-> **Design Patterns**<br>
+> **Design Patterns**
 > **Using Structs to Structure Related Data**
 
 ### Capitalization
@@ -56,28 +56,28 @@ In heading titles, capitalize the first letter of every word **except for**:
 
 - Articles (a, an, the); unless an article is the first word.
 
-  > **Defining an Enum**<br>
-  > **Generic Types and Traits**
+  > **Defining an Enum**
 
 - Coordinating conjunctions (and, but, for, or, nor).
 
+  > **Generic Types and Traits**
   > **Packages and Crates**
 
-- Prepositions of four letters or less; unless these prepositions are the first or last words.
-  - Prepositions of _five_ letters and above should be capitalized (Before, Through, Versus, Among, Under, Between, Without, etc.).
-
-  > **Peripherals as State Machines**
+- Prepositions of _four_ letters or less, unless these prepositions are the first or last words. Prepositions of _five_ letters and above should be capitalized (Before, Through, Versus, Among, Under, Between, Without, etc.).
+  
+  > **Using Structs to Structure Related Data**
+  > **Components: Under the Hood**
 
 Do not capitalize names of functions, commands, packages, websites, etc.
 
-> **What is `assert`**<br>
+> **What is `assert`**
 > **Bringing Paths into Scope with the `use` Keyword**
 
 See also, the [Using `monospace`](#using-monospace) section.
 
 In hyphenated words, do not capitalize the parts following the hyphens.
 
-> **Built-in Targets**<br>
+> **Built-in Targets**
 > **Allowed-by-default Lints**
 
 ## Linking
@@ -101,13 +101,13 @@ Example:
 
 ### Formatting
 
-The Cairo Book usually use the following link formatting:
+The Cairo Book usually uses the following link formatting:
 
-> Instead, you must define a [Trait](https://book.cairo-lang.org/ch08-02-traits-in-cairo.html) and a, ...
+> Instead, you must define a [Trait](./ch08-02-traits-in-cairo.md) and a, ...
 
-- Make intra-book links relative, so they work both online and locally
+- Make intra-book links relative, so they work both online and locally.
 
-Do NOT turn long phrases into links
+Do NOT turn long phrases into links.
 
   > ❌ See the [Cairo Reference’s section on constant evaluation](https://book.cairo-lang.org/ch02-01-variables-and-mutability.html) for more information on what operations can be used when declaring constants.
 
@@ -126,13 +126,13 @@ See also, the [Using `monospace`](#using-monospace) section.
 
 The following types of lists are usually used in documentation:
 
-- **Bullet list** -- use it if the order or items is not important
+- **Bullet list** -- use it if the order of items is not important
 - **Numbered list** -- use it if the order of items is important, such as when describing a process
   - **Procedure** -- special type of numbered list that gives steps to achieve some goal (to achieve this, do this); for an example of a procedure, see the [Usage](https://doc.rust-lang.org/nightly/rustc/profile-guided-optimization.html#usage) section in The rustc book.
 
 ### Formatting
 
-The Cairo Book usually use the following list formatting:
+The Cairo Book usually uses the following list formatting:
 
 - Finish an introductory sentence with a dot.
 - Capitalize the first letter of each bullet point.
@@ -160,29 +160,28 @@ Use monospace font for the following items:
 
 - Code snippets
 
-  - Start the terminal commands with $
-  - Output of previous commands should not start with $
-
+  - Start the terminal commands with `$`
+  - Output of previous commands should not start with `$`
   - Use `bash` syntax highlighting
 
 - Cairo declarations: commands, functions, arguments, parameters, flags, variables
 - In-line command line output
 
   > Writing a program that prints `Hello, world!`
 
-- Data types: `u8`, `u128`
-- Names of crates, traits, libraries,
+- Data types: `u8`, `u128`, etc
+- Names of crates, traits, libraries
 - Command line tools, plugins, packages
 
 ### Monospace and Other Types of Formatting
 
 Monospace font can also be used in:
 
-- links
+- Links
 
-  > [`String`](https://doc.rust-lang.org/std/string/struct.String.html) is a string type provided by ...
+  > [`String`](./ch02-02-data-types.html#string-types) is a string type provided by ...
 
-- headings
+- Headings
 
   > **Serializing with `Serde`**
 
@@ -212,11 +211,11 @@ Monospace font can also be used in:
   >
   > `scarb new hello_world`
   >
-  > 2\. Go into the hello_world directory with the command cd hello_world.
+  > 2\. Go into the _hello_world_ directory with the command cd hello_world
   >
   > `cd hello_world`
 
-- Use _the third person_ (the user, it) when describing how things work from the perspective of hardware or software
+- Use _the third person_ (the user, it) when describing how things work from the perspective of hardware or software.
 
   > Cairo uses an immutable memory model, meaning that once a memory cell is written to, it can't be overwritten but only read from. To reflect this immutable memory model, variables in Cairo are immutable by default.
 
@@ -257,6 +256,8 @@ In markdown:
 > ⚠️ **Note**: Write your note.
 ```
 
+## Appendix A: Existing Style Guides
+
 ### Documentation
 
 - [The Rust Programming Language Style Guide](https://github.com/rust-lang-ja/book-ja/blob/master-ja/style-guide.md)

src/SUMMARY.md

@@ -150,7 +150,7 @@
 - [Starknet Smart Contracts Security](./ch17-00-starknet-smart-contracts-security.md)
 
   - [General Recommendations](./ch17-01-general-recommendations.md)
-  - [Testing Smart Contracts with Starknet Foundry]()
+  - [Testing Smart Contracts]()
   - [Static Analysis Tools](./ch17-03-static-analysis-tools.md)
   - [Formal Verification]()
 

src/appendix-01-keywords.md

@@ -49,7 +49,7 @@ They cannot be used as names of any items.
 
 ---
 
-## Loose keywords
+## Loose Keywords
 
 These keywords are associated with a specific behaviour, but can also be used to define items.
 
@@ -58,7 +58,7 @@ These keywords are associated with a specific behaviour, but can also be used to
 
 ---
 
-## Reserved keywords
+## Reserved Keywords
 
 These keywords aren't used yet, but they are reserved for future use.
 For now, it is possible to use them to define items, although it is highly recommended not to do so.
@@ -84,7 +84,7 @@ Cairo by forbidding them to use these keywords.
 
 ---
 
-## Built-in functions
+## Built-in Functions
 
 The Cairo programming language provides several specific functions that serve a special purpose. We will not cover all of them in this book, but using the names of these functions as names of other items is not recommended.
 

src/appendix-04-common-types-and-traits-and-cairo-prelude.md

@@ -33,7 +33,7 @@ The compiler currently exposes 2 different versions of the prelude:
 - A general version, with a lot of traits that are made available, corresponding to `edition = "2023_01"`.
 - A restricted version, including the most essential traits needed for general cairo programming, corresponding to `edition = 2023_11`.
 
-## List of common types and traits
+## List of Common Types and Traits
 
 The following section provides a brief overview of commonly used types and traits when developing Cairo programs. Most of these are included in the prelude and are therefore not required to be imported explicitly - but not all of them.
 

src/appendix-06-cairo-binaries.md

@@ -1,4 +1,4 @@
-# Appendix F - Installing the Cairo binaries
+# Appendix F - Installing the Cairo Binaries
 
 If you want to have access to the Cairo binaries, for anything that you could not achieve by purely using Scarb you can install them by following the instructions below.
 
@@ -55,7 +55,7 @@ and finally, restart your shell:
 exec $SHELL
 ```
 
-### Set up your shell environment for Cairo
+### Set Up your Shell Environment for Cairo
 
 - Define environment variable `CAIRO_ROOT` to point to the path where
   Cairo will store its data. `$HOME/.cairo` is the default.
@@ -127,7 +127,7 @@ IDE-like popup interface in the terminal window.
 (Note that their completions are independent of Cairo's codebase
 so they might be slightly out of sync for bleeding-edge interface changes.)
 
-### Restart your shell
+### Restart your Shell
 
 for the `PATH` changes to take effect.
 
@@ -176,7 +176,7 @@ is pull the latest changes and rebuild as follows:
 cd $CAIRO_ROOT && git fetch && git pull && cargo build --all --release
 ```
 
-### Step 2: Add Cairo 1.0 executables to your path
+### Step 2: Add Cairo 1.0 Executables to Your Path
 
 ```bash
 export PATH="$CAIRO_ROOT/target/release:$PATH"

src/appendix-07-system-calls.md

@@ -33,16 +33,16 @@ extern fn get_block_hash_syscall(
 
 Gets the hash of a specific StarkNet block within the range of `[first_v0_12_0_block, current_block - 10]`.
 
-#### Return values
+#### Return Values
 
 Returns the hash of the given block.
 
-#### Error messages
+#### Error Messages
 
 - `Block number out of range`: `block_number` is greater than _`current_block`_`- 10`.
 - `0`: `block_number` is less than the first block number of v0.12.0.
 
-#### Common library
+#### Common Library
 
 - [syscalls.cairo](https://github.com/starkware-libs/cairo/blob/0c882679fdb24a818cad19f2c18decbf6ef66153/corelib/src/starknet/syscalls.cairo#L37)
 
@@ -66,11 +66,11 @@ In Cairo 1.0, all block/transaction/execution context getters are batched into t
 
 None.
 
-#### Return values
+#### Return Values
 
 Returns a [struct](https://github.com/starkware-libs/cairo/blob/efbf69d4e93a60faa6e1363fd0152b8fcedbb00a/corelib/src/starknet/info.cairo#L8) containing the execution info.
 
-#### Common library
+#### Common Library
 
 - [syscalls.cairo](https://github.com/starkware-libs/cairo/blob/cca08c898f0eb3e58797674f20994df0ba641983/corelib/src/starknet/syscalls.cairo#L35)
 
@@ -100,11 +100,11 @@ Calls a given contract. This system call expects the address of the called contr
 - _`entry_point_selector`_: A selector for a function within that contract, can be computed with the `selector!` macro.
 - _`calldata`_: The calldata array.
 
-#### Return values
+#### Return Values
 
 The call response, of type `SyscallResult<Span<felt252>>`.
 
-#### Common library
+#### Common Library
 
 - [syscalls.cairo](https://github.com/starkware-libs/cairo/blob/cca08c898f0eb3e58797674f20994df0ba641983/corelib/src/starknet/syscalls.cairo#L10)
 
@@ -136,15 +136,15 @@ Deploys a new instance of a previously declared class.
 - _`calldata`_: The constructor’s calldata. An array of felts.
 - _`deploy_from_zero`_: A flag used for the contract address computation. If not set, the caller address will be used as the new contract’s deployer address, otherwise 0 is used.
 
-#### Return values
+#### Return Values
 
 A tuple wrapped with SyscallResult where:
 
 - The first element is the address of the deployed contract, of type `ContractAddress`.
 
 - The second element is the response array from the contract’s constructor, of type `Span::<felt252>`.
 
-#### Common library
+#### Common Library
 
 - [syscalls.cairo](https://github.com/starkware-libs/cairo/blob/4821865770ac9e57442aef6f0ce82edc7020a4d6/corelib/src/starknet/syscalls.cairo#L22)
 
@@ -170,7 +170,7 @@ For more information and a higher-level syntax for emitting events, see [Starkne
 
 - _`data`_: The event’s data.
 
-#### Return values
+#### Return Values
 
 None.
 
@@ -189,7 +189,7 @@ values.append(3);
 emit_event_syscall(keys, values).unwrap_syscall();
 ```
 
-#### Common library
+#### Common Library
 
 - [syscalls.cairo](https://github.com/starkware-libs/cairo/blob/cca08c898f0eb3e58797674f20994df0ba641983/corelib/src/starknet/syscalls.cairo#L30)
 
@@ -217,11 +217,11 @@ This system call replaces the known delegate call functionality from Ethereum, w
 
 - _`calldata`_: The calldata.
 
-#### Return values
+#### Return Values
 
 The call response, of type `SyscallResult<Span<felt252>>`.
 
-#### Common library
+#### Common Library
 
 - [syscalls.cairo](https://github.com/starkware-libs/cairo/blob/cca08c898f0eb3e58797674f20994df0ba641983/corelib/src/starknet/syscalls.cairo#L43)
 
@@ -249,7 +249,7 @@ For more information, see Starknet’s [messaging mechanism](https://docs.starkn
 
 - _`payload`_: The array containing the message payload.
 
-#### Return values
+#### Return Values
 
 None.
 
@@ -264,7 +264,7 @@ payload.append(2);
 send_message_to_l1_syscall(payload).unwrap_syscall();
 ```
 
-#### Common library
+#### Common Library
 
 - [syscalls.cairo](https://github.com/starkware-libs/cairo/blob/cca08c898f0eb3e58797674f20994df0ba641983/corelib/src/starknet/syscalls.cairo#L51)
 
@@ -292,11 +292,11 @@ Once `replace_class` is called, the class of the calling contract (i.e. the cont
 
 - _`class_hash`_: The hash of the class you want to use as a replacement.
 
-#### Return values
+#### Return Values
 
 None.
 
-#### Common library
+#### Common Library
 
 - [syscalls.cairo](https://github.com/starkware-libs/cairo/blob/cca08c898f0eb3e58797674f20994df0ba641983/corelib/src/starknet/syscalls.cairo#L77)
 
@@ -324,7 +324,7 @@ For information on accessing storage by using the storage variables, see [storag
 
 - _`address`_: The requested storage address.
 
-#### Return values
+#### Return Values
 
 The value of the key, of type `SyscallResult<felt252>`.
 
@@ -339,7 +339,7 @@ let storage_address = storage_base_address_from_felt252(353453575475624637547542
 storage_read_syscall(0, storage_address).unwrap_syscall()
 ```
 
-#### Common library
+#### Common Library
 
 - [syscalls.cairo](https://github.com/starkware-libs/cairo/blob/cca08c898f0eb3e58797674f20994df0ba641983/corelib/src/starknet/syscalls.cairo#L60)
 
@@ -369,10 +369,10 @@ For information on accessing storage by using the storage variables, see [storag
 
 - _`value`_: The value to write to the key.
 
-#### Return values
+#### Return Values
 
 None.
 
-#### Common library
+#### Common Library
 
 - [syscalls.cairo](https://github.com/starkware-libs/cairo/blob/cca08c898f0eb3e58797674f20994df0ba641983/corelib/src/starknet/syscalls.cairo#L70)