From b0fc09e3ad2eb6e33f20f9609e61b1738a3645cc Mon Sep 17 00:00:00 2001
From: Juliana Rat <juli@juli.gay>
Date: Sun, 11 Feb 2024 14:07:12 -0500
Subject: [PATCH] Add basic documentation

---
 README.org             |  40 +++
 doc/guile-termenv.texi | 536 ++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 567 insertions(+), 9 deletions(-)

diff --git a/README.org b/README.org
index 0056068..4b7cff9 100644
--- a/README.org
+++ b/README.org
@@ -2,3 +2,43 @@
 
 #+TITLE: README for Guile-Termenv
 
+~guile-termenv~ is a port of [[https://github.com/muesli/termenv][termenv]] to Guile. It provides a convenient
+interface to ANSI control sequences so you can color and style output without
+need to bother with arcane symbols, all to the height of your terminal's
+capabilities.
+
+While ~guile-termenv~ is not a 1:1 port of ~termenv~, it does provide much of
+the same functionality, and it aims to fill the same niche in the Guile
+ecosystem that ~termenv~ does in the Go ecosystem.
+
+* Building
+
+~guile-termenv~ is developed using [[https://guix.gnu.org][Guix]] and the simplest way to build it is with
+Guix. Running ~guix build -f guix.scm~ will build and test the project, placing
+it in the store. Instead using ~guix shell -f guix.scm~ will create an
+environment with the project, and ~guix profile -if guix.scm~ will install it.
+
+If you wish to use a more manual build methodology, you can replicate the build
+steps like so:
+
+#+BEGIN_SRC shell
+  guix shell -Df guix.scm
+  hall build -x
+  autoreconf -vif
+  ./configure
+  make -j
+#+END_SRC
+
+Note that it is not advised to install the project this way.
+
+If you don't have or don't want to use Guix, ~guile-termenv~ requires the
+following dependencies to build:
+
+- autoconf
+- automake
+- guile-hall
+- pkg-config
+- texinfo
+
+With those dependencies installed, the same build commands as above will work,
+although the ~guix~ command becomes redundant.
diff --git a/doc/guile-termenv.texi b/doc/guile-termenv.texi
index 94807f3..c0b770d 100644
--- a/doc/guile-termenv.texi
+++ b/doc/guile-termenv.texi
@@ -3,14 +3,17 @@
 
 @c %**start of header
 @setfilename guile-termenv.info
-@documentencoding UTF-8
 @settitle Guile-Termenv Reference Manual
+@documentencoding UTF-8
+@documentlanguage en
+@syncodeindex vr fn
+@syncodeindex tp fn
 @c %**end of header
 
 @include version.texi
 
 @copying
-Copyright @copyright{} 2024 
+Copyright @copyright{} 2024 Vivianne Langdon
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -22,12 +25,13 @@ Documentation License''.
 
 @dircategory The Algorithmic Language Scheme
 @direntry
-* Guile-Termenv: (guile-termenv).   
+* Guile-Termenv: (guile-termenv).    ANSI style and color support for
+terminal applications.
 @end direntry
 
 @titlepage
 @title The Guile-Termenv Manual
-@author 
+@author Juliana Rat
 
 @page
 @vskip 0pt plus 1filll
@@ -44,17 +48,531 @@ Edition @value{EDITION} @*
 @top Guile-Termenv
 
 This document describes Guile-Termenv version @value{VERSION}.
+Guile-Termenv is a Guile port of the Go library
+@url{https://github.com/muesli/termenv,termenv}. It analyzes
+information about a terminal's ANSI and color support, then uses this
+to provide a convenient interface for coloring and styling output. It
+is incredibly powerful, and also surprisingly simple. This manual
+provides a brief illustrative tutorial followed by API documentation.
 
 @menu
-* Introduction::                Why Guile-Termenv?
+* Tutorial:: An illustrative tutorial
+* API::      Documentation for public procedures
 @end menu
 
 @c *********************************************************************
-@node Introduction
-@chapter Introduction
+@node Tutorial
+@chapter Tutorial
 
-INTRODUCTION HERE
+TODO
 
-This documentation is a stub.
+@c *********************************************************************
+@node API
+@chapter API
+
+The @code{guile-termenv} API aims to be simple and approachable while
+allowing functional patterns and composition.
+
+@menu
+* Color:: Procedures to colorize text
+* Hyperlink:: Procedures to convert text to hyperlinks
+* Screen:: Procedures for manipulating the terminal screen
+* Style:: Procedures for styling text
+* Unix:: A procedure to determine a terminal's best color profile
+@end menu
+
+@node Color
+@section Color
+
+The @code{(termenv color)} module provides a record type representing
+colors, and a set of procedures for creating and using that record.
+
+Several color-related procedures accept what this documentation refers
+to as a @dfn{hexcode}. Hexcodes are hexadecimal representations of
+binary data associated with color values. Typically, a hexcode
+consists of six hexadecimal digits split into three pairs. The first
+pair represents the red value, the second pair represents the green
+value, and the third pair represents the blue value. It is also
+possible to use a single digit for each value if both digits are the
+same. In this case, only one digit may be used per color.
+
+@code{termenv} accepts hexcodes as strings or as numbers, and it
+recommends numbers. If using numbers, it is further recommended to use
+Guile's base formatting prefix @code{#X} before the value for clarity.
+If using strings, prefixes of any kind are optional and may be either
+@code{#} or @code{0x}.
+
+@deftp {Record} color r g b type
+
+Record representing a color. This record serves as the central data
+type of this module. It has four fields:
+
+@itemize
+@item
+@code{r}: Number in the range 0 to 255 representing the red value of
+the color.
+
+@item
+@code{g}: Number in the range 0 to 255 representing the green value of
+the color.
+
+@item
+@code{b}: Number in the range 0 to 255 representing the blue value of
+the color.
+
+@item
+@code{type}: Either @code{'foreground} or @code{'background}.
+
+@end itemize
+
+@end deftp
+
+@deffn {Procedure} color-r color
+
+Accessor for the @code{r} field of the record @var{color},
+representing its red value.
+
+@end deffn
+
+@deffn {Procedure} color-g color
+
+Accessor for the @code{g} field of the record @var{color},
+representing its green value.
+
+@end deffn
+
+@deffn {Procedure} color-b color
+
+Accessor the @code{b} field of the record @var{color}, representing
+its blue value.
+
+@end deffn
+
+@deffn {Procedure} color? arg
+
+Predicate for whether or not @var{arg} is a @code{color}.
+
+@end deffn
+
+@deffn {Procedure} make-background hex
+
+Create a background @code{color} from the hexcode @var{hex}.
+
+@end deffn
+
+@deffn {Procedure} make-foreground hex
+
+Create a foreground @code{color} from the hexcode @var{hex}.
+
+@end deffn
+
+@deffn {Procedure} hex->color hex [type]
+
+Return a @code{color} representing the hexcode @var{hex}, optionally
+with the given @var{type} (@code{'foreground} or @code{'background}).
+
+@end deffn
+
+@defvr {Parameter} current-color-profile
+
+Symbol representing the color profile of the current output port. The
+possible values are:
+
+@itemize
+@item
+@var{true-color}: Port supports 24-bit ``true color'' representing
+about 16 million colors.
+
+@item
+@var{ansi256}: Port supports a 256-color palette consisting of 216
+colors, 16 ANSI colors, and 24 shades of gray. Color values are
+24-bit.
+
+@item
+@var{ansi}: Port supports 16 colors, bold, italics, and background
+coloration.
+
+@item
+@var{ascii}: Port does not support colors or styles. In practice, this
+means the output port is not a terminal.
+
+@end itemize
+
+@end defvr
+
+@deffn {Procedure} color->sequence color
+
+Return a string of terminal control codes representing the
+@code{color} record @var{color}. Uses @code{current-color-profile}.
+
+@end deffn
+
+@deffn {Procedure} color->ansi color
+
+Convert the 24-bit ``true color'' @var{color} to the nearest ANSI
+color equivalent.
+
+@end deffn
+
+@deffn {Procedure} color->ansi256 color
+
+Convert the 24-bit ``true color'' @var{color} to the nearest 256-color
+ANSI equivalent.
+
+@end deffn
+
+@node Hyperlink
+@section Hyperlink
+
+The @code{(termenv hyperlink)} module provides procedures to create
+active hyperlinks in the terminal.
+
+@deffn {Procedure} hyperlink link [name]
+
+Create a terminal control sequence which displays the optional string
+@var{name} as a hyperlink to @var{link}. If @var{name} is not
+provided, @var{link} is used verbatim.
+
+@end deffn
+
+@deffn {Procedure} format-hyperlink link [name] [port (current-output-port)]
+
+Write the string @var{name} to @var{port}, formatted as a hyperlink to
+@var{link}. This is equivalent to:
+
+@lisp
+(format port (hyperlink link name))
+@end lisp
+
+If @var{name} is not provided, @var{link} is used verbatim. If
+@var{port} is not provided, @code{current-output-port} is used.
+
+@end deffn
+
+@node Screen
+@section Screen
+
+The @code{(termenv screen)} module provides facilities for controlling
+the general state of a terminal.
+
+@deffn {Procedure} reset [port (current-output-port)]
+
+Reset @var{port} to its default state, removing any active styles.
+
+@end deffn
+
+@deffn {Procedure} set-foreground-color hex [port (current-output-port)]
+
+Apply the hexcode @var{hex} as the default foreground color for
+@var{port}.
+
+@end deffn
+
+@deffn {Procedure} set-background-color hex [port (current-output-port)]
+
+Apply the hexcode @var{hex} as the default background color for
+@var{port}.
+
+@end deffn
+
+@deffn {Procedure} set-cursor-color hex [port (current-output-port)]
+
+Apply the hexcode @var{hex} as the default cursor color for
+@var{port}.
+
+@end deffn
+
+@deffn {Procedure} save-screen [port (current-output-port)]
+
+Save the state of @var{port} so that it may be restored later with
+@code{restore-screen}.
+
+@end deffn
+
+@deffn {Procedure} restore-screen [port (current-output-port)]
+
+Restore @var{port} to a state previously saved with
+@code{save-screen}.
+
+@end deffn
+
+Terminals provide a facility called an @dfn{alternate screen} which
+allows a program to write to a blank slate which is wiped away when
+the program terminates. The following procedures allow programmers to
+emit control codes entering and exiting this screen.
+
+@deffn {Procedure} alt-screen [port (current-output-port)]
+
+Switch @var{port} to the alternate screen buffer.
+
+@end deffn
+
+@deffn {Procedure} exit-alt-screen [port (current-output-port)]
+
+Switch @var{port} from the alternate screen buffer to the main screen
+buffer.
+
+@end deffn
+
+@deffn {Procedure} hide-cursor [port (current-output-port)]
+
+Hide the cursor of @var{port}.
+
+@end deffn
+
+@deffn {Procedure} show-cursor [port (current-output-port)]
+
+Show the cursor of @var{port}.
+
+@end deffn
+
+@deffn {Procedure} save-cursor-position [port (current-output-port)]
+
+Save the current position of the cursor of @var{port}.
+
+@end deffn
+
+@deffn {Procedure} restore-cursor-position [port (current-output-port)]
+
+Restore the saved position of the cursor of @var{port}.
+
+@end deffn
+
+Terminals have a concept of a @dfn{scrolling region}. This is the
+region of a terminal screen which is actively being controlled, and
+according to whose coordinates the cursor is moved. Most of the
+following procedures operate on the active scrolling region.
+
+@deffn {Procedure} change-scrolling-region top bottom [port (current-output-port)]
+
+Set the scrolling region of @var{port} to the area from row number
+@var{top} to row number @var{bottom}.
+
+@end deffn
+
+@deffn {Procedure} clear-screen [port (current-output-port)]
+
+Clear the scrolling region of @var{port}.
+
+@end deffn
+
+@deffn {Procedure} move-cursor y x [port (current-output-port)]
+
+Move the cursor of @var{port} to row @var{y} and column @var{x}. Note
+that these values are 1-based, so the top left corner is at the
+coordinates @samp{1,1}.
+
+@end deffn
+
+@deffn {Procedure} scroll-up [amount 1] [port (current-output-port)]
+
+Scroll @var{port} up by @var{amount} rows.
+
+@end deffn
+
+@deffn {Procedure} scroll-down [amount 1] [port (current-output-port)]
+
+Scroll @var{port} down by @var{amount} rows.
+
+@end deffn
+
+@deffn {Procedure} cursor-up [distance 1] [port (current-output-port)]
+
+Move the cursor of @var{port} up @var{distance} rows.
+
+@end deffn
+
+@deffn {Procedure} cursor-down [distance 1] [port (current-output-port)]
+
+Move the cursor of @var{port} down @var{distance} rows.
+
+@end deffn
+
+@deffn {Procedure} cursor-forward [distance 1] [port (current-output-port)]
+
+Move the cursor of @var{port} forward @var{distance} columns.
+
+@end deffn
+
+@deffn {Procedure} cursor-back [distance 1] [port (current-output-port)]
+
+Move the cursor of @var{port} backwards @var{distance} columns.
+
+@end deffn
+
+@deffn {Procedure} cursor-next-line [distance 1] [port (current-output-port)]
+
+Move the cursor of @var{port} up @var{distance} rows and place it at
+the beginning of the line.
+
+@end deffn
+
+@deffn {Procedure} cursor-prev-line [distance 1] [port (current-output-port)]
+
+Move the cursor of @var{port} down @var{distance} rows and place it at
+the beginning of the line.
+
+@end deffn
+
+@deffn {Procedure} clear-line [port (current-output-port)]
+
+Clear the current line of @var{port}.
+
+@end deffn
+
+@deffn {Procedure} clear-line-left [port (current-output-port)]
+
+Clear the current line of @var{port} left of its cursor.
+
+@end deffn
+
+@deffn {Procedure} clear-line-right [port (current-output-port)]
+
+Clear the current line of @var{port} right of its cursor.
+
+@end deffn
+
+@deffn {Procedure} clear-lines n [port (current-output-port)]
+
+Clear @var{n} lines of @var{port}.
+
+@end deffn
+
+@deffn {Procedure} insert-lines n [port (current-output-port)]
+
+Insert @var{n} blank rows at the top of the scrolling region of
+@var{port}, pushing lower rows down.
+
+@end deffn
+
+@deffn {Procedure} delete-lines n [port (current-output-port)]
+
+Delete @var{n} rows at the top of the scrolling region of @var{port},
+pulling any rows below up.
+
+@end deffn
+
+@deffn {Procedure} set-window-title title [port (current-output-port)]
+
+Set the window title of @var{port} to @var{title}.
+
+@end deffn
+
+@node Style
+@section Style
+
+The @code{(termenv style)} module provides procedures for manipulating
+the style and color (@pxref{Color}) of text.
+
+@deffn {Procedure} foreground c s @dots{}
+
+Return a string of terminal control codes representing the string or
+strings @var{s} with the foreground color indicated by the hexcode
+@var{c}.
+
+@end deffn
+
+@deffn {Procedure} background c s @dots{}
+
+Return a string of terminal control codes representing the string or
+strings @var{s} with the background color indicated by the hexcode
+@var{c}.
+
+@end deffn
+
+@deffn {Procedure} bold s @dots{}
+
+Return a string of terminal control codes to render the string or
+strings @var{s} in boldface.
+
+@end deffn
+
+@deffn {Procedure} faint s @dots{}
+
+Return a string of terminal control codes to render the string or
+strings @var{s} faintly.
+
+@end deffn
+
+@deffn {Procedure} italic s @dots{}
+
+Return a string of terminal control codes to italicize the string or
+strings @var{s}.
+
+@end deffn
+
+@deffn {Procedure} underline s @dots{}
+
+Return a string of terminal control codes to underline the string or
+strings @var{s}.
+
+@end deffn
+
+@deffn {Procedure} overline s @dots{}
+
+Return a string of terminal control codes to overline the string or
+strings @var{s}.
+
+@end deffn
+
+@deffn {Procedure} blink s @dots{}
+
+Return a string of terminal control codes to render the string or
+strings @var{s} blinking.
+
+@end deffn
+
+@deffn {Procedure} invert s @dots{}
+
+Return a string of terminal control codes to reverse the string or
+strings @var{s}.
+
+@end deffn
+
+@deffn {Procedure} cross-out s @dots{}
+
+Return a string of terminal control codes to cross out the string or
+strings @var{s} in boldface.
+
+@end deffn
+
+@node Unix
+@section Unix
+
+The @code{(termenv unix)} module provides a single procedure for
+determining the color and control code support of a terminal.
+
+@deffn {Procedure} color-profile port
+
+Test the characteristics of the terminal indicated by @code{port} and
+return a symbol indicating its highest-bit color profile. Returns one
+of:
+
+@itemize
+@item
+@var{true-color}: Port supports 24-bit ``true color'' representing
+about 16 million colors.
+
+@item
+@var{ansi256}: Port supports a 256-color palette consisting of 216
+colors, 16 ANSI colors, and 24 shades of gray. Color values are
+24-bit.
+
+@item
+@var{ansi}: Port supports 16 colors, bold, italics, and background
+coloration.
+
+@item
+@var{ascii}: Port does not support colors or styles. In practice, this
+means the output port is not a terminal.
+
+@end itemize
+
+@end deffn
+
+@node Index
+@unnumbered Index
+
+@printindex fn
 
 @bye