explained #[start] better

book/src/ch1/hello1.md

@@ -83,12 +83,18 @@ much as possible.
 fn main(_argc: isize, _argv: *const *const u8) -> isize {
 ```
 
-This is our `#[start]`. We call it `main`, but the signature looks a lot more
+This is our `#[start]`. We call it `main`, but it's not like a `main` that you'd
-like the main from C than it does the main from Rust. Actually, those inputs are
+see in a Rust program. It's _more like_ the sort of `main` that you'd see in a C
-useless, because nothing will be calling our code from the outside. Similarly,
+program, but it's still **not** that either. If you compile a `#[start]` program
-it's totally undefined to return anything, so the fact that we output an `isize`
+for a target with an OS such as `arm-none-eabi-nm` you can open up the debug
-is vacuously true at best. We just have to use this function signature because
+info and see that your result will have the symbol for the C `main` along side
-that's how `#[start]` works, not because the inputs and outputs are meaningful.
+the symbol for the start `main` that we write here. Our start `main` is just its
+own unique thing, and the inputs and outputs have to be like that because that's
+how `#[start]` is specified to work in Rust.
+
+If you think about it for a moment you'll probably realize that, those inputs
+and outputs are totally useless to us on a GBA. There's no OS on the GBA to call
+our program, and there's no place for our program to "return to" when it's done.
 
 ```rust
   unsafe {

docs/ch1/hello1.html

@@ -209,12 +209,17 @@ much as possible.</p>
 <pre><pre class="playpen"><code class="language-rust">#[start]
 fn main(_argc: isize, _argv: *const *const u8) -&gt; isize {
 </code></pre></pre>
-<p>This is our <code>#[start]</code>. We call it <code>main</code>, but the signature looks a lot more
+<p>This is our <code>#[start]</code>. We call it <code>main</code>, but it's not like a <code>main</code> that you'd
-like the main from C than it does the main from Rust. Actually, those inputs are
+see in a Rust program. It's <em>more like</em> the sort of <code>main</code> that you'd see in a C
-useless, because nothing will be calling our code from the outside. Similarly,
+program, but it's still <strong>not</strong> that either. If you compile a <code>#[start]</code> program
-it's totally undefined to return anything, so the fact that we output an <code>isize</code>
+for a target with an OS such as <code>arm-none-eabi-nm</code> you can open up the debug
-is vacuously true at best. We just have to use this function signature because
+info and see that your result will have the symbol for the C <code>main</code> along side
-that's how <code>#[start]</code> works, not because the inputs and outputs are meaningful.</p>
+the symbol for the start <code>main</code> that we write here. Our start <code>main</code> is just its
+own unique thing, and the inputs and outputs have to be like that because that's
+how <code>#[start]</code> is specified to work in Rust.</p>
+<p>If you think about it for a moment you'll probably realize that, those inputs
+and outputs are totally useless to us on a GBA. There's no OS on the GBA to call
+our program, and there's no place for our program to &quot;return to&quot; when it's done.</p>
 <pre><pre class="playpen"><code class="language-rust">
 # #![allow(unused_variables)]
 #fn main() {

docs/ch1/hello2.html

@@ -234,6 +234,10 @@ pub unsafe fn mode3_pixel(col: isize, row: isize, color: u16) {
   (VRAM as *mut u16).offset(col + row * SCREEN_WIDTH).write_volatile(color);
 }
 </code></pre></pre>
+<p>Exact same program that we started with, but much easier to read.</p>
+<p>Of course, in the full <code>gba</code> crate that this book is a part of we have these and
+other elements all labeled and sorted out for you. Still, for educational
+purposes it's often best to do it yourself at least once.</p>
 
                     </main>
 

docs/print.html

@@ -363,12 +363,17 @@ much as possible.</p>
 <pre><pre class="playpen"><code class="language-rust">#[start]
 fn main(_argc: isize, _argv: *const *const u8) -&gt; isize {
 </code></pre></pre>
-<p>This is our <code>#[start]</code>. We call it <code>main</code>, but the signature looks a lot more
+<p>This is our <code>#[start]</code>. We call it <code>main</code>, but it's not like a <code>main</code> that you'd
-like the main from C than it does the main from Rust. Actually, those inputs are
+see in a Rust program. It's <em>more like</em> the sort of <code>main</code> that you'd see in a C
-useless, because nothing will be calling our code from the outside. Similarly,
+program, but it's still <strong>not</strong> that either. If you compile a <code>#[start]</code> program
-it's totally undefined to return anything, so the fact that we output an <code>isize</code>
+for a target with an OS such as <code>arm-none-eabi-nm</code> you can open up the debug
-is vacuously true at best. We just have to use this function signature because
+info and see that your result will have the symbol for the C <code>main</code> along side
-that's how <code>#[start]</code> works, not because the inputs and outputs are meaningful.</p>
+the symbol for the start <code>main</code> that we write here. Our start <code>main</code> is just its
+own unique thing, and the inputs and outputs have to be like that because that's
+how <code>#[start]</code> is specified to work in Rust.</p>
+<p>If you think about it for a moment you'll probably realize that, those inputs
+and outputs are totally useless to us on a GBA. There's no OS on the GBA to call
+our program, and there's no place for our program to &quot;return to&quot; when it's done.</p>
 <pre><pre class="playpen"><code class="language-rust">
 # #![allow(unused_variables)]
 #fn main() {
@@ -761,6 +766,10 @@ pub unsafe fn mode3_pixel(col: isize, row: isize, color: u16) {
   (VRAM as *mut u16).offset(col + row * SCREEN_WIDTH).write_volatile(color);
 }
 </code></pre></pre>
+<p>Exact same program that we started with, but much easier to read.</p>
+<p>Of course, in the full <code>gba</code> crate that this book is a part of we have these and
+other elements all labeled and sorted out for you. Still, for educational
+purposes it's often best to do it yourself at least once.</p>
 
                     </main>