From afb9e2ce43c334ef03cfa9d6254d4c2570d70847 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Diego=20Fernando=20Carri=C3=B3n?= <diego@crthaze.com>
Date: Mon, 12 Aug 2024 23:11:45 +0200
Subject: [PATCH] fleshout readme

---
 README.md | 93 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 91 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 99d38c5..76ccacc 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # VT Tools
 
-VT Tools is a Go library for providing support for Digital Equipment
+vtTools is a Go library for providing support for Digital Equipment
 Corporation Video Terminals to Go programs.
 
 **It currently only supports the DEC VT220 in 8-bit Mode.**
@@ -16,4 +16,93 @@ This library aims to allow developers to write Go code (in UTF-8) which can
 be run correctly on DEC Video Terminals.
 
 It also provides *some* support for manipulating the terminal in additional ways
-according to its documented spec.
+according to its documented spec. (See the section on Control Sequences below)
+
+## Usage
+
+In the simplest terms, this library allows you to create objects which represent
+the DEC terminal, which can be used to write UTF-8 encoded strings to a real
+hardware DEC terminal (or an extremely faithful emulator) safely.
+
+It does this by translating UTF-8 Characters to the appropriate codepoints on
+the limited character encoding used by DEC terminals, and invoking the
+necessary control sequences to remap additional characters to these codepoints
+when needed.
+
+#### Create a Terminal
+
+Terminals are attached to an `io.Writer` (usually `os.Stdout`) which will send
+the data to the Hardware terminal.
+
+```go
+var term = NewVT220(os.Stdout)
+```
+
+#### Use the Terminal as a writer.
+
+Terminals implement the `io.Writer` interface themselves (they effectively
+wrap the `io.Writer` they were assigned at creation), and can be passed to
+programs that need to write safely to the screen.
+
+```go
+term := NewVT220(os.Stdout)
+logger := zerolog.New(term)
+```
+
+#### Use the Terminal instead of `fmt`.
+
+In order to safely print to the screen, you can use the term instead of
+the `fmt` package.
+
+```go
+import (
+	stdFmt "fmt"
+
+	"git.sdf.org/CRThaze/vtTools/vt220"
+)
+
+fmt := NewVT220(os.Stdout)
+
+func testPrint() error {
+	// Yes, the standard library fmt.Print(f|ln)? functions
+	// can also return errors.
+	_, err := fmt.Println("Hello World!")
+	if err != nil {
+		return stdFmt.Errorf("Failed to print: %v", err)
+	}
+	return nil
+}
+```
+
+#### Invoke Arbitrary Control Sequences
+
+DEC Terminals support their own proprietary control sequences. Terminal objects
+provide some helper functions for easily using some of these, especially
+for swapping character sets (some of these are handled automatically when
+writing to or printing with the terminal object).
+
+The [DEC VT220 Programmers Reference Manual](https://web.archive.org/web/20230928233241/vt100.net/docs/vt220-rm/chapter4.html)
+describes numerous control sequences which can be used to enable various feautres
+and functions.
+
+They characters that make them up are indicated in the manual by either a mnemonic or
+character from the standard character sets, as well as a Column / Row above these.
+It is very easy invoke any combination of control characters using these:
+
+```go
+import (
+	"git.sdf.org/CRThaze/vtTools/vt220"
+)
+
+term := NewVT220(os.Stdout)
+
+func main() {
+	cs := vt220.NewControlSequence(
+		// The characters from the C0 and C1 ranges can be refrenced by either
+		// their coordinates (C00R01) or their mnemonic (as below).
+		vt220.ESC,
+		vt220.C02R09,
+	)
+	term.InvokeCtrlSequence(cs)
+}
+```