From 87eb5b7fbd3d74e4815539ea8e5ee3bb070c3d25 Mon Sep 17 00:00:00 2001
From: Joshua Bemenderfer <josh@thederf.com>
Date: Tue, 21 Feb 2023 12:59:37 -0500
Subject: [PATCH] Beginning to improve c docs.

---
 docs/src/docs/c.tce | 68 +++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 65 insertions(+), 3 deletions(-)

diff --git a/docs/src/docs/c.tce b/docs/src/docs/c.tce
index 91ff310..f7cedf5 100644
--- a/docs/src/docs/c.tce
+++ b/docs/src/docs/c.tce
@@ -25,10 +25,59 @@ Section light
     Heading 2 Getting Started
       class mt-12 mb-6
     Markdown
-      The core terrace parser is distributed as a single-header C library.<br/>
-      To use it, download [parser.h](https://git.thederf.com/thederf/Terrace/src/branch/main/packages/c/parser.h) and include in your project tree.
+      The terrace parser is distributed as a set of C header files.<br/>
+      To use it, download and include the following files in your project tree:
+      - [parser.h](https://git.thederf.com/thederf/Terrace/src/branch/main/packages/c/parser.h) - Core terrace parser
+      - [document.h](https://git.thederf.com/thederf/Terrace/src/branch/main/packages/c/document.h) - (optional) Convenience functions for parsing of documents
     CodeBlock c
-      #include "parser.h"
+      // Provides getline() for reading from stdin
+      #include <stdio.h>
+      // Provides free() for deallocating the lines from getline()
+      #include <stdlib.h>
+      // Provides document API for interacting with Terrace files
+      #include "document.h"
+
+      // Custom userData struct. Stores information needed
+      // by read_line below.
+      typedef struct read_line_container_s {
+        size_t bufsize;
+      } read_line_container_t;
+
+      // A user-supplied function to read lines from stdin (or whichever data source you choose)
+      int read_line_from_stdin(char** line, void* userData) {
+        read_line_container_t* lineContainer = (read_line_container_t*) userData;
+        // Uses getline from the C stdlib to read the next line from stdin.
+        int num_chars_read = getline(line, &lineContainer->bufsize, stdin);
+        // Change trailing newline to null char. Terrace doesn't use trailing newlines
+        if (num_chars_read > 0) (*line)[num_chars_read - 1] = '\0';
+        // Return the number of charaters read to the document parser.
+        return num_chars_read;
+      }
+
+      int main(int argc, char *argv[]) {
+        read_line_container_t read_line_information = { .bufsize = 64 };
+        // Initialize the terrace document with the line reader function created above.
+        terrace_document_t doc = terrace_create_document(' ', &read_line_from_stdin, &read_line_information);
+
+        // Loop over every line in the document.
+        while(terrace_next(&doc, -1)) {
+          // > Replace with your custom line handling code.
+
+          // Print the line and level to demonstrate the terrace_level and terrace_line functions.
+          printf("| level %u | line %s |", terrace_level(&doc), terrace_line(&doc, -1));
+          // If one of the lines starts with "title", output it.
+          if (terrace_match(&doc, "title")) {
+            printf("Title: %s |", terrace_tail(&doc));
+          }
+        };
+
+        // Free allocated line memory
+        free(line);
+
+        return 0;
+      }
+
+    Markdown
 
     Heading 2 Recipes
       class mt-12
@@ -111,16 +160,29 @@ Section light
     Heading 2 Core API
       class mt-12
 
+    Markdown
+      In most cases, you'll use the [Document API](#document-api) instead.
+      The Core API provides low-level parsing for individual lines.
+
     Heading 3 terrace_linedata_t
       class my-6
     CodeBlock c
+      // Holds the parsed information from each line.
       typedef struct terrace_linedata_s {
+        // Which character is being used for indentation. Avoids having to specify it on each terrace_parse_line call.
         char indent;
+        // How many indent characters are present in the current line before the first non-indent character.
         unsigned int level;
+        // The number of characters before the start of the line's "head" section.
+        // (Normally the same as `level`)
         unsigned int offsetHead;
+        // The number of characters before the start of the line's "tail" section.
         unsigned int offsetTail;
       } terrace_linedata_t;
 
+    Heading 3 terrace_create_line_data()
+      class my-6
+
     Heading 3 terrace_parse_line()
       class my-6
     CodeBlock c