commit - 40b59c550a9ef5b90c932f4b5820f4fbd632b353
commit + 6940039126d2c5974f86df4fe6052796f5c0f2ea
blob - /dev/null
blob + 94584f258b2f5e352dbef609346055db7993504f (mode 644)
--- /dev/null
+++ README.md
@@ -0,0 +1,96 @@
+# README.md
+
+__aestel__
+
+A collection of Lua terminal utilities.
+
+## An Aestel?
+
+The aestel project is named for the Old English _æstel_, a wax  
+tablet used for recording and preserving knowledge.
+
+__aestel__ is a collection of lightweight, modular utilities for  
+terminal-based workflow, productivity, knowledge management, and  
+system administration.
+
+## Project Structure
+
+The utilities are ports of the author's shell scripts to Lua. At  
+present they include the following scripts.
+
+    browsefilies.lua     Directory browsing and file opening
+    launchprogram.lua    Menu-driven program launcher
+    setbackground.lua    Background setting utility
+
+The utilities are scripts written in Lua that rely on a shared set  
+of Lua modules.
+
+     browse.lua       Browsing directory structure and content.
+     colors.lua       Shared ANSI color constants.
+     display.lua      Shared terminal output display.
+     input.lua        Shared low-level terminal input utilities.
+     menu.lua         Rendering and navigating menus.
+     opener.lua       Opening files based on MIME type.
+
+- bin/: User-facing scripts (browsefiles, launchprogram, etc.)
+- aestel/: Shared Lua modules providing the core UI/navigation primitives
+- man/: Manual pages for the utilities
+
+## Scripting Language Dependencies
+
+- Lua 5.4
+- LuaFileSystem (lfs)
+
+### Preferred Program Dependencies
+
+Aestel is designed to be modular. The following programs are used  
+by default for their alignment with the author's design values  
+(written in C, minimal, and Unix-compliant):
+
+- Terminal Emulator: [st](https://st.suckless.org)
+- Text Editor: [vis](https://github.com/martanne/vis), and,
+- Background Setter: [bgs](https://github.com/Gottox/bgs).
+
+These programs are not strictly required. Users may substitute their  
+preferred programs. Note that doing so will require modification of  
+the relevant Lua script or module source code.
+
+## Install
+
+Install the libraries, binaries, and manual pages. Note that root  
+privileges are not required as the default destination `~/.local/`  
+directory.
+
+```
+make install
+```
+
+## Uninstall
+
+Remove the libraries, binaries, and manual pages.
+
+```
+make uninstall
+```
+
+## Configuration
+
+Configuration of the user's configuration file for the user's  
+interactive shell is required for scripts to exit to the current  
+working directory. The author uses the Almquist Shell and places  
+the following in `~/.ashrc` file.
+
+```
+browsefiles() {
+    local target
+    target=$(command browsefiles "$@")
+    [ -n "$target" ] && [ -d "$target" ] && cd "$target"
+}
+
+setbackground() {
+    local target
+    target=$(command setbackground "$@")
+    [ -n "$target" ] && [ -d "$target" ] && cd "$target"
+}
+```
+