Do an editing pass of the book using chatgpt (#398)

- [x] Changelog updated / no changelog update needed

README.md

@@ -1,4 +1,4 @@
-# AGBRS
+# AGB
 
 ## Rust for the Game Boy Advance
 
@@ -10,17 +10,17 @@
 ![AGB logo](.github/logo.png)
 
 This is a library for making games on the Game Boy Advance using the Rust
-programming language. It attempts to be a high level abstraction over the
-internal workings of the Game Boy Advance whilst still being high performance
-and memory efficient.
+programming language. The library's main focus is to provide an abstraction
+that allows you to develop games which take advantage of the GBA's capabilities
+without needing to have extensive knowledge of its low-level implementation.
 
-AGBRS provides the following features:
+agb provides the following features:
 
 * Simple build process with minimal dependencies
 * Built in importing of sprites, backgrounds, music and sound effects
 * High performance audio mixer
-* Simple sprite and tiled background usage
-* Global allocator allowing for use of both `core` and `alloc`
+* Easy to use sprite and tiled background usage
+* A global allocator allowing for use of both `core` and `alloc`
 
 The documentation for the latest release can be found on
 [docs.rs](https://docs.rs/agb/latest/agb/).
@@ -69,7 +69,7 @@ to just write games for the Game Boy Advance using this library:
 * [gbafix](https://crates.io/crates/gbafix)
     * Install with `cargo install gbafix`
 
-With all of this installed, you should be able to run a full build of agbrs using by running
+With all of this installed, you should be able to run a full build of agb using by running
 ```sh
 just ci
 ```
@@ -103,15 +103,14 @@ for performant decimals.
 
 ## Stability
 
-While in 0.x releases, we are following a semi-semantic versioning.
-So 0.x.y will be compatible with 0.x.z provided that y > z, but any changes
-to the minor version will be incompatible with one another.
+While agb is in the pre-1.0 phase, we follow a semi-semantic versioning scheme to ensure compatibility between minor releases.
+Specifically, any 0.x.y release is guaranteed to be compatible with another 0.x.z release provided that y > z, but there may be breaking changes between minor releases (i.e., changes to the second digit, e.g., between 0.1 and 0.2).
 
-Once we hit version 1.0, we will maintain stronger semantic versioning.
+Once agb reaches version 1.0, we will transition to stronger semantic versioning, meaning that any breaking changes will be indicated by an increment to the major version (i.e., the first digit, e.g., from 1.0 to 2.0).
 
 ## Acknowledgments
 
-AGBRS would not be possible without the help from the following (non-exhaustive) list of projects:
+agb would not be possible without the help from the following (non-exhaustive) list of projects:
 
 * The amazing work of the [rust-console](https://github.com/rust-console) for making this all possible in the first place
 * The [asefile](https://crates.io/crates/asefile) crate for loading aseprite files
@@ -120,15 +119,15 @@ AGBRS would not be possible without the help from the following (non-exhaustive)
 
 ## Licence
 
-AGBRS and all its subcrates are released under MPL version 2.0. See full licence
+agb and all its subcrates are released under MPL version 2.0. See full licence
 text in the `LICENSE` file.
 
-AGBRS contains a subset of the code from [agbabi](https://github.com/felixjones/agbabi) which is released under a zlib style licence,
+agb contains a subset of the code from [agbabi](https://github.com/felixjones/agbabi) which is released under a zlib style licence,
 details for which you can find under `agb/src/agbabi`.
 
 The template is released under [CC0](https://creativecommons.org/share-your-work/public-domain/cc0/) to allow you to make whatever
 changes you wish.
 
-The AGBRS logo is released under [Creative Commons Attribution-ShareAlike 4.0](http://creativecommons.org/licenses/by-sa/4.0/)
+The agb logo is released under [Creative Commons Attribution-ShareAlike 4.0](http://creativecommons.org/licenses/by-sa/4.0/)
 
 The music used for the examples is by [Josh Woodward](https://www.joshwoodward.com) and released under [Creative Commons Attribution 4.0](https://creativecommons.org/licenses/by/4.0/)

book/src/hardware/hardware.md

@@ -1,21 +1,20 @@
 # The Game Boy Advance hardware
 
-The Game Boy Advance was released by Nintendo in Japan in March 2001 and in North America in the following June.
-It has a 2.9 inch screen with a 240x144 pixel resolution, and contains a 32-bit 16.8MHz ARM CPU.
-It was developed to be the successor to the Game Boy Color and internally codenamed the 'Advanced Game Boy' (agb) which is where this crate gets its name.
+The Game Boy Advance is a handheld gaming console released by Nintendo in March 2001 in Japan and in North America in June of the same year.
+It features a 2.9 inch screen with a 240x144 pixel resolution and is powered by a 32-bit 16.8MHz ARM CPU.
+The console was developed as a successor to the Game Boy Color and was internally codenamed the 'Advanced Game Boy' (agb), which is where this crate gets its name.
 
 # What makes the GBA unique?
 
-The Game Boy Advance is (fairly) unique amongst retro handheld consoles.
-It was developed at a time where processors weren't powerful enough to be able to push an entire screen of pixels to the screen every frame.
-Therefore, it has a special Pixel Processing Unit (PPU) which is sort of similar to a modern day graphics card, except it is very games focused.
-For example, the GBA has a concept of 'hardware sprites' and 'hardware backgrounds' which we'll go in to more detail in the next section.
-This hardware 2d capabilities gives the GBA the unique characteristics with the games developed for it.
+The Game Boy Advance is a (fairly) unique console among retro handheld consoles.
+It was developed at a time when processors were not powerful enough to push an entire screen of pixels to the screen every frame.
+As a result, it features a special Pixel Processing Unit (PPU) that is similar to a modern-day graphics card, but is optimized for gaming.
+The console has a concept of "hardware sprites" and "hardware backgrounds," which we will explain in more detail in the next section.
+These hardware 2D capabilities give the GBA its unique characteristics.
 
-However, despite this, it is possible to write code for it using modern tools and programming languages thanks to the ARM CPU it contains.
-The CPU is modern enough to be supported by LLVM and rust to give a reasonably trouble free experience.
-
-So the GBA lets you take advantage of modern tooling while also giving you the ability to see what programming for retro consoles was like at the time!
+Despite being a retro console, the GBA is still compatible with modern tools and programming languages thanks to the ARM CPU it contains.
+The CPU is modern enough to be supported by LLVM and Rust, which provide a reasonably trouble-free experience.
+This allows developers to take advantage of modern tooling while experiencing what it was like to program for retro consoles at the time.
 
 # Capabilities of the hardware
 
@@ -25,9 +24,8 @@ The relevant features for this book are:
 * 256 sprites which can be from 8x8 to 64x64 pixels in size
 * 4 background layers which are enabled / disabled depending on the graphics mode
 * Background tiles, 8x8 pixel tiles are used in the background layers if they are in tile mode.
-* 8-bit sound. You have the ability to send 8-bit raw audio data to the speakers (optionally stereo).
+* 8-bit sound. You have the ability to send 8-bit raw audio data to the speakers, optionally stereo.
 
 You can read more about the specifics of the GBA on [gbatek](https://rust-console.github.io/gbatek-gbaonly/).
-
-agb tries to abstract some of this away from you to give you less to remember and less that can go wrong.
-If you want to try playing around directly with the hardware, the best place to look is [tonc](https://www.coranac.com/tonc/text/).
+To simplify the development process, agb abstracts some of the GBA's hardware away from the developer, which reduces the number of things to remember and lessens the chance of something going wrong.
+If you wish to experiment with the hardware directly, the best place to look is [tonc](https://www.coranac.com/tonc/text/).

book/src/introduction/introduction.md

@@ -1,30 +1,52 @@
 # Introduction
 
-**agb** is a library for writing games for the Game Boy Advance (GBA) in rust.
-It is intended to make the process of producing games for the Game Boy Advance as easy as possible by giving you access to the hardware in an abstracted format, which allows you to take advantage of all that it has to offer, without needing to know the specifics of how it is implemented.
+**agb** is a powerful and easy-to-use library for writing games for the Game Boy Advance (GBA) in rust.
+It provides an abstracted interface to the hardware, allowing you to take full advantage of its capabilities without needing to know the low-level details of its implementation.
+
+## A little bit about agb
+
+`agb` is a library for making games on the Game Boy Advance using the Rust
+programming language. The library's main focus is to provide an abstraction
+that allows you to develop games which take advantage of the GBA's capabilities
+without needing to have extensive knowledge of its low-level implementation.
+
+agb provides the following features:
+
+* Simple build process with minimal dependencies
+* Built in importing of sprites, backgrounds, music and sound effects
+* High performance audio mixer
+* Easy to use sprite and tiled background usage
+* A global allocator allowing for use of both `core` and `alloc`
+
+## Why rust?
+
+Rust is an excellent choice of language for developing games on low-level embedded hardware like the GBA.
+Its strong type system, memory safety, and performance optimizations make it well-suited for building reliable and efficient code in this context.
+
+Agb leverages rust's unique features by using the type system to model the GBA's hardware.
+This approach helps prevent common programming errors and allows developers to quickly build games that function correctly on the GBA platform.
+
+In addition to safety and correctness, rust's performance optimizations are crucial for developing games on the GBA's slow processor.
+With a limited amount of time per frame, every optimization counts, and rust's speed and efficiency help ensure that games built with agb run smoothly on the GBA hardware.
 
 # What is in this book?
 
-This book is intended as an introduction to what **agb** has to offer, and should set you up nicely to start writing games of your own.
-This book will not give a thorough overview of the specifics of the hardware implementation of the GBA unless it is needed as part of an explanation.
-An overview of the hardware can be found in chapter 2.
+This book serves as an introduction to agb, showcasing its capabilities and providing guidance on how to use it to build your own GBA games.
+It assumes that you have some experience with rust and game development, and provides detailed explanations of the unique challenges of writing games for the GBA.
 
 # Who is this book for?
 
-This book is for:
-* **People who want to make games for the GBA.** First and foremost, games written using agb cannot run on any other platform except the GBA and emulators. If you don't want to write a game for the GBA, you should probably use a different library.
-* **People who have experience in rust.** Unless the rust specific syntax or semantics are important, we will not discuss details here and instead recommend reading the rust book before coming back.
-* **People with experience in writing games.** Game programming is hard, and harder still in rust on a GBA. We recommend writing a game for a more user friendly platform before coming back here.
-
-If you fit into all of those categories, welcome!
-It is super rewarding being able to play a game you made yourself on a piece of 20+ year old hardware.
+This book is ideal for anyone interested in writing games for the GBA using rust.
+If you're new to either rust or game development, you may want to start with some introductory resources before diving into this book.
+This book assumes a basic understanding of rust syntax and semantics, as well as game development concepts.
 
 # Helpful links
 
-* [agb's GitHub](https://github.com/agbrs/agb) all development happens here
-* [agb's Discussion Page](https://github.com/agbrs/agb/discussions) a forum where you can ask for help on the usage of agb
-* [agb's crates.io page](https://crates.io/crates/agb)
-* [agb's documentation](https://docs.rs/agb) which is useful if you need a quick reference
-* [Awesome Game Boy Advance development](https://github.com/gbdev/awesome-gbadev) contains links to popular libraries, emulators and the super friendly gbadev discord
-* [Example game](https://lostimmortal.itch.io/the-hat-chooses-the-wizard) written using agb as part of the 2021 GMTK game jam.
-* [More example games](https://github.com/agbrs/agb/releases/latest) built using agb. See them in `examples.zip` attached to the latest release.
+* [agb's GitHub](https://github.com/agbrs/agb) is the primary development hub for the library.
+* [agb's Discussion Page](https://github.com/agbrs/agb/discussions) is a helpful forum where you can ask for help on using agb or share your projects with the community.
+* [agb's crates.io page](https://crates.io/crates/agb) the latest version of the library on crates.io.
+* [agb's documentation](https://docs.rs/agb) is a useful reference for the library's API and features.
+* [Awesome Game Boy Advance development](https://github.com/gbdev/awesome-gbadev) is a comprehensive resource for GBA development, with links to popular libraries, emulators, and the friendly gbadev Discord server.
+* [Example games](https://github.com/agbrs/agb/releases/latest) built using agb can be found in the `examples.zip` file attached to the latest release. Additionally, you can also check out [The Hat Chooses the Wizard](https://lostimmortal.itch.io/the-hat-chooses-the-wizard), a game written using agb as part of the GMTK 2021 game jam.
+
+In addition to these resources, this book provides step-by-step instructions for getting started with agb.

book/src/pong/01_introduction.md

@@ -1,25 +1,23 @@
-# Learn agb part I - pong
+# Learn agb part I: Pong
 
-In this section, we'll make a simple pong style game for the Game Boy Advance using `agb`.
-You will learn:
+In this section, you'll learn how to make a simple pong-style game for the Game Boy Advance using agb.
+By following the steps in this section below, you'll gain an understanding of:
 
 * How to use tiled graphics modes.
 * How to import graphics using `agb`.
-* What Game Boy Advance sprites are and how to put them on the screen.
-* How to detect button input and react to it.
-* How to add a static background.
-* How to make a dynamic background for a score display.
-* How to add music to your game.
-* How to add sound effects to your game.
+* What Game Boy Advance sprites are, how to create them, and how to display them on the screen.
+* How to detect button input and use it to control game objects.
+* How to add a static background to your game.
+* How to make a dynamic background to display scores.
+* How to add music and sound effects to your game.
 
-With this knowledge, you'll be well equipped to start making your own games!
+With this knowledge, you'll be well equipped to start making your own games for the GBA!
 
 ## Getting started
 
-To start, create a new repository based on the [agb template](https://github.com/agbrs/template).
-We'll call this `pong`.
+To get started, create a new repository based on the [agb template](https://github.com/agbrs/template) and name it `pong`.
 
-Then replace the `name` field in `Cargo.toml` with `pong`, to end up with something similar to:
+Next, update the `name` field in `Cargo.toml` to `pong` like so:
 
 ```toml
 [package]
@@ -31,4 +29,4 @@ edition = "2021"
 # ...
 ```
 
-You are now ready to get started learning about how `agb` works.
+Now, you're ready to dive and and start learning about `agb`!

book/src/pong/02_the_gba_struct.md

@@ -4,14 +4,17 @@ In this section, we'll cover the importance of the Gba struct and how it gets cr
 
 # The importance of the Gba struct
 
-Almost all interaction with the Game Boy Advance's hardware goes through the [Gba singleton struct](https://docs.rs/agb/latest/agb/struct.Gba.html).
-You should not create the Gba struct yourself, instead having it be passed into your main function.
+The [Gba singleton struct](https://docs.rs/agb/latest/agb/struct.Gba.html) is a crucial part of agb game development.
+It is used for almost all interactions with the Game Boy Advance's hardware, such as graphics rendering, timer access and audio playback.
 
-The Gba struct is used to take advantage of rust's borrow checker, and lean on it to ensure that access to the Game Boy Advance hardware is done 'sensibly'.
-You won't have to worry about 2 bits of your code modifying data in the wrong way!
+You should not create the Gba struct yourself. Instead, it is passed to your main function as an owned reference.
+This allows rust's borrow checker to ensure that access to the Game Boy Advance hardware is done in a safe and sensible manner, preventing two bits of your code from modifying data in the wrong way.
 
 # How all agb games start
 
+To use the Gba struct in your agb game, you'll need to create a function (normally called `main`) which takes an owned reference to the Gba instance.
+The recommended way to do this is by using the `#[agb::entry]` attribute macro provided by the `agb` crate.
+
 Replace the content of the `main` function with the following:
 
 ```rust,ignore
@@ -23,15 +26,14 @@ loop {} // infinite loop for now
 # }
 ```
 
-and ignore warnings for now.
+This creates an infinite loop and allows you to start building your game.
 
 # Running your pong game
 
-Although there isn't much to see at the moment (just a black screen), you can start the game by using `cargo run` or whatever worked for you in the introduction.
-
-# What we did
+At this point, your game won't do much except display a black screen. To run your game, use the `cargo run` command as before.
 
-This was a very simple but incredibly important part of any game using `agb`.
-All interactions with the hardware are gated via the Gba struct, which you never create yourself.
+# What we covered
 
-You are now ready to learn about display modes and how to start getting things onto the screen!
+In this section, we covered the importance of the Gba struct in agb game development.
+By using the Gba struct as a gatekeeper for all hardware interactions, you can ensure that your code is safe and efficient.
+You are now ready to learn about sprites and start getting things onto the screen!