feat(doc/buzbee): Added IF tables, added doc building system and updated stylesheet, removed pdf for now

.gitignore

@@ -7,6 +7,7 @@
 build/
 map.txt
 bbmkhash
+*.pdf
 
 # Build system generated files
 src/version.s

docs/buzbee.typ

@@ -11,26 +11,187 @@
   author: [Gale Faraday],
 )
 
-= Introduction
-#lorem(120)
+= Introduction <intro>
+
+BUZBEE is a "machine language monitor" styled after Steve Wozniak's WOZMON for
+the CHIBI PC-09 hobby computer platform. It is the stock bootloader and
+interface for the PC-09. This manual goes over the usage of BUZBEE, and some of
+the technical internals of how it works and how to hack on it.
+
+The CHIBI PC-09 name and platform is copyright 2024-2025 Amber Zeller. The CHIBI
+PC-09 BIOS is copyright 2024-2025 Gale Faraday and Amber Zeller. BUZBEE is
+copyright 2025 Gale Faraday. All CHIBI PC-09 components are licensed under the
+MIT license.
+
 #pagebreak()
 
-= BUZBEE Functions
-#lorem(120)
+= BUZBEE Functions <bbfunc>
+
+BUZBEE is at its core a chain loader or bootloader. This means that most of the
+functionality of the CHIBI starts with using BUZBEE. BUZBEE functions are broken
+into two categories: _Internal Functions_ or "IFs," and _External Functions_ or
+"EFs." IFs are native routines mapped to textual commands entered at the BUZBEE
+prompt. EFs are native routines called through IFs. EFs can either be any user
+supplied code, or one of a set of routines in the BIOS/BUZBEE ROM or "firmware".
+
 #pagebreak()
 
-== Internal Functions (IFs)
-#lorem(120)
+== Internal Functions (IFs) <if-top>
+
+Internal Functions are the textual commands that BUZBEE interprets from the
+command line to execute the user's wish. Internal Functions are canonically
+listed in alphabetical order. Below in @if-table is a list of available IFs.
+
+#figure(
+  table(
+    columns: (1fr, auto),
+    inset: 10pt,
+    align: center,
+    table.header(
+      [*Name* (pg. no.)], [*Description*]
+    ),
+    [`CALL` #ref(<if-call>, form: "page")],
+    [Call a resident routine in the MPU's address space.],
+    [`HELP` #ref(<if-help>, form: "page")],
+    [Display a summary of known commands.],
+    [`PEEK` #ref(<if-peek>, form: "page")],
+    [Dumps memory from the MPU's address space to the terminal.],
+    [`POKE` #ref(<if-poke>, form: "page")],
+    [Overwrites memory in the MPU's address space.],
+    [`SREC` #ref(<if-srec>, form: "page")],
+    [Switches into Motorola S-Record receive mode.],
+  ),
+  caption: [Table of IFs],
+) <if-table>
+
+In the following pages these IFs are described in specific.
+
+// TODO: Talk about how IFs are tokenized.
+
 #pagebreak()
 
-== External Functions (EFs) & User Programs
+#let _ifpagehead(
+  desc: none,
+  syntax: none,
+  params: (),
+) = {
+  smallcaps[#desc]
+  parbreak()
+  [Syntax: #syntax]
+  parbreak()
+  [Parameters: ]
+  if params.len() > 0 {
+    for (param, desc) in params [
+      - #raw("<" + upper(param) + ">"): #desc
+    ]
+  } else {
+    text(style: "italic")[N/A]
+  }
+}
+
+=== IF: `CALL` <if-call>
+
+#_ifpagehead(
+  desc: "Calls a resident routine in the MPU's address space.",
+  syntax: [`CALL <PTR>`],
+  params: (
+    ptr: "An absolute pointer to a position in the 6309 MPU's memory map.",
+  ),
+)
+
 #lorem(120)
+
+// TODO: For when CHIBI PC-09 Prototype #2 comes out or whenever we get banking
+// add it here "Special care must be taken to properly bank in the correct
+// memory banks before executing this command." yadda yadda
+
 #pagebreak()
 
-= BUZBEE Reserved Memory Regions
-#lorem(120)
+=== IF: `HELP` <if-help>
+
+#_ifpagehead(
+  desc: "Displays a summary of available IFs.",
+  syntax: [`HELP`],
+  params: ()
+)
+
+`HELP` does what it says on the tin. It should be noted that between Git tags of
+the firmware the message displayed by this may be incomplete or innaccurate.
+Internally all this does is print a string with the UART using the `POUTZSTR`
+BIOS routine.
+
 #pagebreak()
 
-= Building BUZBEE
+=== IF: `PEEK` <if-peek>
+
+#_ifpagehead(
+  desc: "Dumps memory from the MPU's address space to the terminal.",
+  syntax: [`PEEK <BASE> [<HIGH>]`],
+  params: (
+    base: [
+      The address of the byte to dump or the base (lower bound) address of the
+      byte to start dumping from if `<HIGH>` is specified.
+    ],
+    high: [
+      An optional operand given as the upper bound of the range to dump. Forms
+      a range together with `<BASE>`.
+    ],
+  )
+)
+
 #lorem(120)
 
+#pagebreak()
+
+=== IF: `POKE` <if-poke>
+
+#_ifpagehead(
+  desc: "Writes values to the MPU's address space.",
+  syntax: [`POKE <ADDR> <BYTES>`],
+  params: (
+    addr: "The base (low) address to start writing bytes from.",
+    bytes: "The bytes to write into memory separated by whitespace.",
+  )
+)
+
+#lorem(120)
+
+#pagebreak()
+
+=== IF: `SREC` <if-srec>
+
+#_ifpagehead(
+  desc: "Switches into Motorola S-Record receive mode.",
+  syntax: [`SREC`],
+  params: (),
+)
+
+#lorem(120)
+
+#pagebreak()
+
+== External Functions (EFs) <ef-top>
+
+#lorem(120)
+
+=== EFs in ROM <ef-rom>
+
+#lorem(120)
+
+#pagebreak()
+
+= BUZBEE Reserved Memory Regions <res-mem>
+
+#lorem(120)
+
+#pagebreak()
+
+= Building CHIBI PC-09 Firmware from Source <building>
+
+#lorem(120)
+
+#pagebreak()
+
+= BUZBEE Internals and Modding <internals>
+
+#lorem(120)

docs/style.typ

@@ -9,7 +9,7 @@
   // Global page format
   set page(
     paper: "us-letter",
-    header: align(right, text(9pt, weight: "light")[#title]),
+    header: align(right, text(10pt, weight: "light")[#title]),
     numbering: "1",
   )
 
@@ -28,13 +28,17 @@
   // Heading numbering
   set heading(numbering: "1.1")
 
+  // Show table captions above tables
+  show figure.where(kind: table): set figure.caption(position: top)
+
   // Title page and TOC
   page(header: none, footer: none)[
     // Emit title and subtitle page
     #block(height: 60%)[
       #align(center + horizon,
         block(text(22pt)[#title]) +
-        block(above: 2em)[#smallcaps[#subtitle]]
+        block(above: 2em)[#smallcaps[#subtitle]] +
+        block[Written by #author],
       )
     ]
     // Emit TOC

makefile

@@ -1,6 +1,6 @@
 # Makefile for CHIBI PC-09 Firmware
 
-.PHONY: generate all clean
+.PHONY: generate all clean docs
 .IGNORE: clean
 .DEFAULT_GOAL := all
 
@@ -33,6 +33,9 @@ LDFLAGS := -f srec -m map.txt -s linkscript
 # Rules and Phony Targets
 # ------------------------------------------------------------------------------
 
+docs: docs/*.typ
+	typst compile docs/buzbee.typ
+
 all: $(TARGROM)
 
 # Fix srec into flashable bin file