From a917d2995ab90b025d8650bd59536b0f6353b877 Mon Sep 17 00:00:00 2001
From: Adam Shamblin <adam@vexingworkshop.com>
Date: Sun, 26 Jun 2022 15:54:53 -0600
Subject: [PATCH] Add to docs

---
 README.md       |  2 +-
 doc/README.md   | 13 +++++++++++
 doc/index.md    |  5 -----
 doc/terminal.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++
 doc/uart.md     | 50 ++++++++++++++++++++++++++++++++++++++++++
 src/uart.fs     | 10 ++++++---
 6 files changed, 129 insertions(+), 9 deletions(-)
 create mode 100644 doc/README.md
 delete mode 100644 doc/index.md
 create mode 100644 doc/terminal.md
 create mode 100644 doc/uart.md

diff --git a/README.md b/README.md
index 262677a..45b621c 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,7 @@ keywords:
 The purpose of this project is to build a general purpose, interactive computer
 out of an rp2040, while learning practical programming using the Forth language.
 
-[Documentation](doc/index.md)
+[Documentation](doc/README.md)
 
 
 ## TODO
diff --git a/doc/README.md b/doc/README.md
new file mode 100644
index 0000000..a6ad8b0
--- /dev/null
+++ b/doc/README.md
@@ -0,0 +1,13 @@
+---
+title: Documentation
+---
+
+# Documentation
+
+Here may be found the documentation for the words and capabilities made
+available using the `forthdeck` project.
+
+* [GPIO](gpio.md)
+* [Terminal](terminal.md)
+* [UART](uart.md)
+* [Wordle](wordle.fs)
diff --git a/doc/index.md b/doc/index.md
deleted file mode 100644
index a50ead8..0000000
--- a/doc/index.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-title: Documentation
----
-
-* [GPIO](gpio.md)
diff --git a/doc/terminal.md b/doc/terminal.md
new file mode 100644
index 0000000..708ab42
--- /dev/null
+++ b/doc/terminal.md
@@ -0,0 +1,58 @@
+---
+title: Terminal
+file: terminal.fs
+---
+
+# Terminal
+
+The Terminal library provides words for working with serial input and output,
+including screen management and color display.
+
+## Escape Characters & Color Codes
+
+### ESC[ ( -- )
+
+Send an ANSI escape character to the terminal. This is intended to precede ANSI
+escape codes.
+
+## Terminal UI
+
+### TI ( -- ), TE ( -- )
+
+Enter or exit TUI mode.
+
+### at-xy ( column, row )
+
+Place the cursor at the specified column and row on screen.
+
+```forth
+5 5 at-xy
+```
+
+### \[home\] ( -- )
+
+Place the cursor at the 1,1 position on screen.
+
+### page ( -- )
+
+Clear the screen and place the cursor at the 1,1 position on screen.
+
+### hide-cursor ( -- ), show-cursor (--)
+
+Hide or show the cursor.
+
+### cleanup ( -- )
+
+After completing a TUI application, clear the screen, exit TUI mode and display
+the cursor.
+
+## Colors
+
+Terminal text may be formatted using typical ANSI color and formatting codes.
+
+```forth
+[black][red/bg]Black on red text[reset]
+```
+
+Further "true color" words may be created using `ESC[` and extended ANSI color
+codes.
diff --git a/doc/uart.md b/doc/uart.md
new file mode 100644
index 0000000..1e6db07
--- /dev/null
+++ b/doc/uart.md
@@ -0,0 +1,50 @@
+---
+title: UART
+file: uart.fs
+---
+
+# UART
+
+The UART library provides words for working with the rp2040's two UART serial
+interfaces. This includes matters of hardware flow control.
+
+The rp2040 has two UART serial interfaces, referred to by the constants UART0
+and UART1.
+
+## Diagram
+
+**TODO** Put ASCII diagram connecting FTDI module and Pico here
+
+## Enabling & Disabling Interfaces
+
+### enabled? ( addr -- flag )
+
+Determine if a UART interface is enabled.
+
+```forth
+UART0 enabled?
+```
+
+### transmit-enabled? ( addr -- flag )
+
+Determine if a UART interface has transmit enabled.
+
+```forth
+UART0 transmit-enabled?
+```
+
+### rts-enabled? ( addr -- flag ), cts-enabled? ( addr -- flag )
+
+Determine if RTS or CTS are enabled for the given interface.
+
+```forth
+UART0 rts-enabled?
+```
+
+### rts-toggle ( addr -- ), cts-toggle ( addr -- )
+
+Enable or disable RTS or CTS for the given interface.
+
+```forth
+UART0 rts-toggle
+```
diff --git a/src/uart.fs b/src/uart.fs
index 5d6765e..d9b13b9 100644
--- a/src/uart.fs
+++ b/src/uart.fs
@@ -11,8 +11,12 @@ $030 constant UARTCR
 UART0_BASE UARTCR + constant UART0_CR
 UART1_BASE UARTCR + constant UART1_CR
 
+\ Convenience words for referencing control registers
+: UART0 ( -- addr ) UART0_CR ;
+: UART1 ( -- addr ) UART1_CR ;
+
 \ Determine if UART is enabled at this interface
-\ example: UART0_CR enabled?
+\ example: UART0 enabled?
 : enabled? ( addr -- flag ) @ 1 AND 0 > ;
 : transmit-enabled? ( addr -- flag ) @ 1 8 lshift AND 0 > ;
 
@@ -20,5 +24,5 @@ UART1_BASE UARTCR + constant UART1_CR
 : rts-enabled? ( addr -- flag ) @ 1 14 lshift AND 0 > ;
 : cts-enabled? ( addr -- flag ) @ 1 15 lshift AND 0 > ;
 
-: rts-toggle ( addr -- flag ) dup @ 1 14 lshift XOR swap ! ;
-: cts-toggle ( addr -- flag ) dup @ 1 15 lshift XOR swap ! ;
+: rts-toggle ( addr -- ) dup @ 1 14 lshift XOR swap ! ;
+: cts-toggle ( addr -- ) dup @ 1 15 lshift XOR swap ! ;
-- 
2.39.5