fatty 0.99.0 → 0.99.3

data/README.org

@@ -1,4 +1,4 @@
-#+BEGIN_EXPORT markdown
+#+OPTIONS: toc:4 H:4
 #+PROPERTY: header-args:ruby :results value :colnames no :hlines yes :exports both :dir "./"
 #+PROPERTY: header-args:ruby+ :wrap example :session fatty_session :eval yes
 #+PROPERTY: header-args:ruby+ :prologue "$:.unshift('./lib') unless $:.first == './lib'; require 'fatty'"
@@ -6,74 +6,843 @@
 #+PROPERTY: header-args:sh :exports code :eval no
 #+PROPERTY: header-args:bash :exports code :eval no
 
-[![CI](https://github.com/ddoherty03/fatty/actions/workflows/main.yml/badge.svg?branch=master)](https://github.com/ddoherty03/fatty/actions/workflows/main.yml)
-#+END_EXPORT
+* Introduction
+~Fatty~ aims to provide a full-featured command-line environment that provides:
 
+1. an emacs-like editing command-line input, including undo/redo and kill/yank
+2. a history facility,
+3. command completion,
+4. completion of partially-typed file path names,
+5. output into a paging environment,
+6. searching within the paged output,
+7. issuing messages to a "status" area separate from the output pane,
+8. binding keys to pre-defined actions,
+9. defining unrecognized key-codes as named keys,
+10. color themes that can be selected in real time,
+11. a way to define new themes,
+12. processing completed command lines with a callback procedure of your
+    choosing,
+13. several user-interface widgets such as selection popups, text prompts,
+    menus, and progress indicators,
+14. a way to render markdown to the output pane,
 
-#+PROPERTY: header-args:ruby :results value :colnames no :hlines yes :exports both :dir "./"
-#+PROPERTY: header-args:ruby+ :wrap example :session fatty_session :eval yes
-#+PROPERTY: header-args:ruby+ :prologue "$:.unshift('./lib') unless $:.first == './lib'; require 'fatty'"
-#+PROPERTY: header-args:ruby+ :ruby "bundle exec irb"
-#+PROPERTY: header-args:sh :exports code :eval no
-#+PROPERTY: header-args:bash :exports code :eval no
+In other words, fatty allows you to write a terminal-based REPL of your choosing but takes
+care of all the difficult parts.
 
-* Introduction
+~Fatty~ is written entirely in Ruby and was born from my frustrations at the
+limitations of libraries like ~readline~ and ~reline~.  It uses ~curses~ and
+~truecolor~ sequences for low-level rendering and is surprisingly snappy.
 
-* Reading Keys
+~Fatty~ is /not/ a terminal emulator but runs on top of one.
 
-Shift/Ctrl/Meta F-keys are normalized when ncurses provides distinct constants.
+* Quick Start
+** Installing
+~Fatty~ is a ruby gem, so it can be installed with
 
-* Fatty Help
-** The =fatty= demo command
+#+begin_src sh :tangle no
+  $ gem install fatty
+#+end_src
 
-When you =fatty=, it operates as a simple demo of the =fatty= gem by
-presenting an editable command-line using emacs key bindings.  It has several
-builtin commands to demonstrate =fatty= features, and any command it does not
-recognized is handed off to the shell.
+** Trying it Out with the `fatty` Demo
+Once installed, you can try out ~fatty~ with the included program called
+~fatty~.  It allows you to easily exercise all of the important features of the
+~fatty~ library.  At a normal shell prompt simply type ~fatty~, and it will
+launch the ~fatty~ demo program.
 
-** Builtin commands
+Once inside ~fatty~ you will be prompted with a prompt that names your current
+directory.  Type ~help~ to get a summary of the builtin commands available to
+you.  If you type anything other than a builtin command, ~fatty~ attempts to
+run it as a shell command and displays the output.
 
+*** Builtin commands
 Here are the commands builtin to =fatty=
 
-| Command                     | Description                                                             |
-|-----------------------------+-------------------------------------------------------------------------|
-| help                        | Display this file on the output pane                                    |
-| cd                          | Change the current directory used by the shell                          |
-| choose                      | Present a series of choices in a popup window                           |
-| choosevals                  | Also present choices in a popup window but return an associated value   |
-| choose_multi                | Present choices with a "checkbox" for selecting multiple values         |
-| choosevals_multi            | Also present a checkbox but return associated values                    |
-| menu                        | Present a menu of labeled routines to run                               |
-| info                        | Display an "info" message on the status line                            |
-| good                        | Display a "good" message colored to indicate success                    |
-| warn                        | Display a "warn" message colored to indicate caution                    |
-| oops                        | Display an "oops" message colored to indicate failure                   |
-| prompt                      | Popup a text box for entering a value in response to a prompt           |
-| progress count <N>          | Display an animated progress indicator counting up to 40 or the given N |
-| progress percent <N>        | Same but also show the percent complete                                 |
-| progress simple_percent <N> | Same but show only the percent complete                                 |
-| progress trail              | Show progress by displaying an "indicator" character for each step      |
-| progress bar                | Show progress by a filling bar using ASCII characters                   |
-| progress unicode_bar        | Same, but using unicode characters                                      |
-| progress braille_bar        | Same, but using braille characters                                      |
-| progress spinner            | Animate a "spinner" showing a busy state                                |
-| markdown <file.md>          | Render the markdown file to the output pane; defaults to a demo file    |
-| keytest                     | Enter key diagnostic mode report keycodes, key names, and bindings      |
-
-
-** Keybindings
-
-The following tables explain the keybindings available in `fatty` in different
-contexts.  Named keys are indicated by `:name` and key categories, such as
-`<digits>` are indicated with brackets.
+| Command                    | Description                                                             |
+|----------------------------+-------------------------------------------------------------------------|
+| help                       | Display this file on the output pane                                    |
+| cd                         | Change the current directory used by the shell                          |
+| choose                     | Present a series of choices in a popup window                           |
+| choosevals                 | Also present choices in a popup window but return an associated value   |
+| choose_multi               | Present choices with a "checkbox" for selecting multiple values         |
+| choosevals_multi           | Also present a checkbox but return associated values                    |
+| menu                       | Present a menu of labeled routines to run                               |
+| info                       | Display an "info" message on the status line                            |
+| good                       | Display a "good" message colored to indicate success                    |
+| warn                       | Display a "warn" message colored to indicate caution                    |
+| oops                       | Display an "oops" message colored to indicate failure                   |
+| interrupt                  | Test fatty's interrupt handling                                          |
+| prompt                     | Popup a text box for entering a value in response to a prompt           |
+| progress count <N>         | Display an animated progress indicator counting up to 40 or the given N |
+| progress percent <N>       | Same but also show the percent complete                                 |
+| progress count_percent <N> | Same but show both count and the percent complete                       |
+| progress trail             | Show progress by displaying an "indicator" character for each step      |
+| progress bar               | Show progress by a filling bar using ASCII characters                   |
+| progress unicode_bar       | Same, but using unicode characters                                      |
+| progress braille_bar       | Same, but using braille characters                                      |
+| progress spinner           | Animate a "spinner" showing a busy state                                |
+| markdown <file.md>         | Render the markdown file to the output pane; defaults to a demo file    |
+| keytest                    | Enter key diagnostic mode to report keycodes, key names, and bindings   |
+| colors                     | Display ANSI, 256-color, and X11 color diagnostics                      |
 
-*** Input Context
+*** Screenshots
+
+**** Command line editing
+
+Here is the command line, mid-edit showing a region selected and, in dim text
+to the right, a predictive completion based on history.
+
+#+CAPTION: Input editing showing region and predictive completion.
+#+ATTR_HTML: :alt Fatty command line screenshot :width 900
+[[file:images/input_editing.png]]
+
+**** Searchable Output
+
+While paging output, you can search for words, as here the user searches for
+the word =tty= in the output.  The current match is highlighted in yellow with
+other matches highlighted in gray.  The paging status line shows the search
+term and the direction of search.  The user can navigate for other matches in
+the output using =n= and =N=.
+
+#+CAPTION: Searching for instances of =tty= in the output.
+#+ATTR_HTML: :alt Fatty search pane :width 900
+[[file:images/search_output.png]]
+
+**** Paging Markdown
+
+The ~fatty~ demo running the =markdown= command and paging the output.  It
+shows =fatty's= ability to render markdown using ANSI codes, including
+colorizing code blocks, as well as its paging interface.
+
+#+CAPTION: Running the =fatty= demo =markdown= command.
+#+ATTR_HTML: :alt Fatty terminal UI demo screenshot :width 900
+[[file:images/page_markdown.png]]
+
+**** Popup Selection
+One of the many "widgets" available through =fatty= is the ability to present
+the user with a set of choices to select from.  After running the demo's
+=choose "AAA" "BBB" "CCC" "DDD" "EEE"=
+
+#+CAPTION: Running the =fatty= demo =choose= command.
+#+ATTR_HTML: :alt Fatty terminal UI demo screenshot :width 900
+[[file:images/choose_popup.png]]
+
+* Usage
+** Launching a Fatty Terminal
+*** =on_accept=
+You can launch a ~Fatty~ terminal session that does arbitrary processing of an
+edited command line and returns a String to be displayed on the output pane by
+providing an =on_accept= proc as a parameter as shown in this file that we'll
+call ~loudrev~:
+
+#+begin_src ruby :tangle no
+  #! /usr/bin/env ruby
+  # -*- mode: ruby -*-
+
+  require 'fatty'
+
+  loud_reversal = lambda do |line|
+    line.upcase.reverse
+  end
+
+  Fatty::Terminal.new(
+    on_accept: loud_reversal,
+  ).go
+#+end_src
+
+Now you have an interactive application that allows you to type text and see
+what it looks like when written backwards in uppercase letters. It's as easy
+as that!
+
+When a =fatty= application runs, =fatty= installs a few files if they do not
+exist:
+
+- a history file at =~/.fatty_history=
+- a config directory at =~/.config/fatty= that contains
+  + =config.yml=, the main configuration file
+  + =keydefs.yml=, a file for associating keycodes emitted by the underlying
+    terminal with names when curses does not do so automatically,
+  + =keybindings.yml=, a file for associating named keys with actions above
+    and beyond the emacs bindings that are used by default, and
+  + =themes=, a directory of pre-defined theme definitions that you can choose
+    from and add to by adding your own themes.
+
+**** Parameters to =on_accept=
+The =on_accept= proc passed to an instance of =Fatty::Terminal= can take one
+or two parameters: (1) =line=, the edited line as it exists when the user
+types =RETURN= and (2) an optional callback parameter that you can use to
+access the facilities of =fatty=.
+
+**** The =line= parameter to =on_accept=
+=Fatty= does not parse command lines for your application.  When the user
+accepts a =line=, =Fatty= passes the line to =on_accept= as text.  It is up to
+your callback to decide whether to strip whitespace, split words, interpret
+quotes, parse options, recognize subcommands, or treat punctuation specially.
+
+This keeps =Fatty= useful for many different kinds of REPLs.  Some applications
+want shell-like parsing.  Others want to preserve the user's input exactly.
+
+For shell-like parsing, Ruby's standard =Shellwords= library is often useful:
+
+#+begin_src ruby :tangle no
+  #! /usr/bin/env ruby
+  # -*- mode: ruby -*-
+
+  require 'fatty'
+  require 'shellwords'
+
+  runner = lambda do |line, fatty|
+    words = Shellwords.split(line)
+
+    case words
+    when ["echo", *rest]
+      fatty.append("#{rest.join(" ")}\n")
+    when ["count", *rest]
+      fatty.append("#{rest.length}\n")
+    when []
+      fatty.status("Blank line", role: :info)
+    else
+      fatty.alert("Unknown command: #{words.first}", role: :warn)
+    end
+  rescue ArgumentError => e
+    fatty.alert("Could not parse line: #{e.message}", role: :error)
+  end
+
+  Fatty::Terminal.new(
+    prompt: "shellwords> ",
+    on_accept: runner,
+  ).go
+#+end_src
+
+**** The callback parameter to =on_accept=
+The =on_accept= proc can have a second parameter named whatever you like that
+serves as a callback into certain facilities provided by =fatty=.  In this
+README we use the name =fatty= for the callback parameter since it provides
+access to the facilities provided by the =fatty= library.  Here is a variation
+of the prior example that also echoes the original typed string into the
+so-called status area:
+
+#+begin_src ruby :tangle no
+  #! /usr/bin/env ruby
+  # -*- mode: ruby -*-
+
+  require 'fatty'
+
+  loud_reversal = lambda do |line, fatty|
+    fatty.good(line)
+    line.upcase.reverse
+  end
+
+  Fatty::Terminal.new(
+    on_accept: loud_reversal,
+  ).go
+#+end_src
+
+The callback parameter responds to several methods that allow your
+application to interact with the user.  They are documented below.
+
+**** Output ordering
+The =on_accept= callback can send text to the output pane in three ways:
+
+1. by returning a value from the callback;
+2. by calling =append= or =markdown= on the callback environment; or
+3. by calling =append_now= on the callback environment.
+
+A returned =String= is the simplest output mechanism.  It is displayed after
+the callback finishes:
+
+#+begin_src ruby :tangle no
+  Fatty::Terminal.new(
+    on_accept: ->(line) { line.upcase.reverse },
+  ).go
+#+end_src
+
+Calls to =append= and =markdown= also queue output until the callback finishes.
+If a callback both calls =append= or =markdown= and returns a =String=, the
+queued output is displayed first and the returned string is displayed after it.
+
+Calls to =append_now= are different.  They append text and immediately render a
+frame, so the user can see output while the callback is still running.  Use
+=append_now= for long-running callbacks that should stream progress to the
+output pane.
+
+At the end of the callback, =Fatty= finishes the command and updates the pager
+state.  Output produced with =append_now= may therefore appear during the
+callback, while output from =append=, =markdown=, and the callback's return
+value appears after the callback returns.
+
+**** Long-running callbacks and interruption
+The =on_accept= callback runs synchronously.  While it is running, control does
+not return to Fatty's normal event loop.  A callback that performs lengthy work
+should therefore provide explicit safe points at which the user may interrupt
+it:
+
+#+begin_src ruby :tangle no
+  runner = lambda do |_line, fatty|
+    records.find_each do |record|
+      process(record)
+      fatty.check_interrupt!
+    end
+    fatty.good("Processing complete.")
+  end
+#+end_src
+
+The =check_interrupt!= method performs a throttled, nonblocking input check.  If
+the user has typed C-c or C-g, it raises =Fatty::Interrupt=.  Fatty catches that
+exception at the callback boundary, finishes the current command cleanly, and
+returns to the normal input loop.
+
+Calls to =check_interrupt!= should be placed only at points where it is safe to
+stop the application work.  For example, they can go between records, batches,
+files, or other complete units of work.  Fatty does not interrupt callbacks
+asynchronously and does not stop threads or raise exceptions at arbitrary
+instructions.
+
+Fast callbacks do not need to call =check_interrupt!=.  Long-running callbacks
+that already update a shared progress facility can often place the check there
+so that individual commands do not need separate interruption logic.
+
+Code that needs to report interruption before allowing Fatty to perform its
+normal cleanup may rescue and re-raise the exception:
+
+#+begin_src ruby :tangle no
+  begin
+    items.each do |item|
+      process(item)
+      fatty.check_interrupt!
+    end
+  rescue Fatty::Interrupt
+    fatty.warn("Processing interrupted.", replace: true)
+    raise
+  else
+    fatty.good("Processing complete.", replace: true)
+  end
+#+end_src
+
+**** ANSI colors in output
+Text passed to =append=, =append_now=, =status=, and =alert= may contain ANSI
+SGR color/style sequences. Fatty interprets those sequences relative to the
+current theme role, so an ANSI reset returns to the active Fatty role rather
+than to the terminal's physical default colors.  =fatty= includes the nice
+[[https://github.com/ku1ik/rainbow][=Rainbow= gem]] for colorizing text as a convenience.
+
+*** Other parameters to =Terminal.new=
+When building a REPL with =Terminal.new= you can also supply several other
+parameters:
+
+- =prompt:= :: a =String= or a zero-argument callable such as a =Proc= or
+  =lambda= that returns the prompt used for the input line to be edited.
+  Because it can be a callable, it can change after each run of =on_accept=;
+  if not given, it defaults to '> ';
+- =app_name= :: the name for the "app" using the =fatty= library; this allows
+  app-specific configuration under =~/.config/fatty/apps/<app_name>= or a
+  different directory specified by =app_config_dir=;
+- =app_config_dir= :: an alternative directory for app-specific configuration
+  instead of the default;
+- =completion_proc= :: a callable that takes the current text of the input
+  field's buffer and returns an =Array= of possible completions at that point
+  in the input; by default, there is no completion proc;
+- =history_path= :: a =String= for the file path where command history is
+  loaded from and saved.  The default, =:default=, uses =history.file= from
+  Fatty's configuration, falling back to =~/.fatty_history= if no history file
+  is configured.  Passing =nil= or =false= disables persistent history and
+  keeps history in memory only.  Passing a string uses that path directly.
+- =history_ctx= :: optional history context used to prefer relevant history
+  entries.  It may be a hash or a callable returning a hash.  The context is
+  stored in the history file with each accepted line and is used by history
+  navigation and history autosuggestions.  Matching context entries are
+  preferred, but history is not strictly partitioned; Fatty can still fall
+  back to other entries.  This is useful when the same application wants
+  different history behavior in different directories, ledgers, projects,
+  modes, or accounts.
+
+For example, the =fatty= demo executable uses the current working directory as
+history context:
+
+#+begin_src ruby :tangle no
+  Fatty::Terminal.new(
+    history_ctx: -> { { pwd: Dir.pwd } },
+    on_accept: ->(line, env) {
+      # ...
+    },
+  ).go
+#+end_src
+
+With that setup, commands entered in =~/src/byr= are favored when the terminal
+is again in =~/src/byr=, while commands entered elsewhere remain available as
+fallback history.
+
+** The Callback API
+Here are the details on the messages that you can send to the callback
+parameter to the =on_accept= proc.
+
+*** =append(text, follow: true)=
+Add the given text to the output pane.  After a full page of output is
+produced, enter paging mode so the user can view the output at leisure and
+search the output. If =follow= is true, keep the output pane's viewport
+covering the last lines of output.
+
+*** =append_now(text, follow: true, mode: nil)=
+Like =append=, but display output as it is produced rather than wait for a
+full page to be produced.
+
+Setting the mode to =:scrolling= or =:paging= determines whether the output is
+scrolled continuously or paused on each page of output.
+
+*** =markdown(text)=
+Render the given text as markdown source according to the current theme then
+=append= the result to the output pane.
+
+We will not rehearse here how to compose markdown, but one thing that is a bit
+special with =fatty= is forcing a line break: you should use =<br>= to force a
+line break in the middle of a line.
+
+#+begin_example
+This line has a forced line break <br> and this should appear on the next line.
+#+end_example
+
+will render as
+
+#+begin_example
+This line has a forced line break
+and this should appear on the next line.
+#+end_example
+
+*** =status(text, role: :info)=
+Display the text in the "status" area, the lines immediately above the input
+field, using one of the following "roles":
+- :good :: colored to indicate something affirming according to the theme,
+  usually something greenish;
+- :info :: colored something neutral simply for informational purposes;
+- :warn :: colored something to suggest caution, usually something in the
+  orange to yellow range;
+- :error :: colored something to suggest danger, usually some tone of red.
+
+*** =good(text, replace: false, render: true)=
+Display the text in the status area with the role :good.
+
+*** =info(text, replace: false, render: true)=
+Display the text in the status area with the role :info.
+
+*** =warn(text, replace: false, render: true)=
+Display the text in the status area with the role :warn.
+
+*** =error(text, replace: false, render: true)=
+Display the text in the status area with the role :error.
+
+*** =oops(text, replace: false, render: true)=
+An alias for =error(text)=
+
+*** =alert(text, role: :info)=
+Display the text in the one-line alert panel just below the input field.  In
+the alert panel, the role only controls the foreground color, not the
+background.
+
+*** =prompt(prompt, initial: "", cancel_value: nil, history_key: nil, save_history: true)=
+Display a popup dialog box that allows the user to type in any string and
+return it.  Combine the input line with a prompted-for string and shuffle
+their letters together:
+
+#+begin_src ruby :tangle no
+#! /usr/bin/env -S ruby -Ilib
+# -*- mode: ruby -*-
+
+require 'fatty'
+
+weaver = lambda do |line, fatty|
+  str = fatty.prompt("Secondary string to weave in with '#{line}'")
+  (line + str).downcase.gsub(/[^a-z]/, '').split('').shuffle.join
+end
+
+Fatty::Terminal.new(
+  on_accept: weaver,
+  prompt: "Primary String> "
+).go
+#+end_src
+
+You can pre-fill the prompt's input line by passing in an =initial:=
+parameter.
+
+The =prompt= input has its own history facility separate from the history in
+the main input command line.  You can turn it off by setting =save_history= to
+=false=.
+
+=prompt= returns whatever the user typed and returns =nil= if the user cancels
+with C-c or C-g unless you specify an alternative =cancel_value=.
+
+*** =check_interrupt!=
+Provide a cooperative interruption point during a long-running =on_accept=
+callback.  Fatty periodically performs a nonblocking input check and raises
+=Fatty::Interrupt= if the user has typed C-c or C-g.
+
+The polling is throttled, so =check_interrupt!= may be called frequently.  It
+should nevertheless be called only at points where the callback can safely
+stop its work.
+
+Fatty catches =Fatty::Interrupt= at the callback boundary, finishes the current
+command, restores the terminal state, and resumes the normal input loop.
+
+*** =add_progress(label:, total: nil, style: :percent, role: :info, width: 40)=
+Display a progress widget in the status area to show the user that the system
+is working, not frozen.  The =add_progress= method returns a =Progress= object
+on which the =#update= method can be called to cause it to animate one step.
+To the left of the widget the =label:= is displayed, followed by the widget.
+For processes where the total size is known in advance, the =total:= parameter
+indicates that size.  The =role:= parameter controls the styling of the
+widget. The =width:= parameter places a limit on the size of the widget.
+=Fatty= supports several styles of progress widgets:
 
+- :spinner :: a simple busy-wait indicator that just animates on every call;
+- :count :: count up to =total= on each call of =update(current: <count>)=
+- :percent :: count up to percent of =total= on each call of =update(current: <count>)=
+- :count_percent :: count up and show percent of =total= on each call of =update(current: <count>)=
+- :bar :: display a filling ASCII progress bar with percent and count
+- :unicode_bar :: display a filling Unicode progress bar with percent and count
+- :braille_bar :: display a filling progress bar with percent and count using
+  braille characters
+- :trail :: display an "indicator" on each call of =update(indicator: <string>)=
+
+**** Initialization =add_progress(label:, style: :percent, total: nil, role: :info, width: 40)=
+
+- =label:= :: Text displayed before the progress widget, "Progress" by default.
+- =style:= :: The style of the progress widget from one of those named above.
+- =total:= :: For all styles except :trail and :spinner, the number that
+  represents the size of the task.  As the =#update= calls increase the value
+  of =current= towards =total=, the widget indicates increasing completion.
+- =role:= :: One of :good, :info, :warn, or :error to color the widget
+  according to the theme's idea of these roles.  By default, :info.
+- =width= :: The number of characters for the full widget display: it is only
+  relevant for the bar styles and the trail style; otherwise it is ignored.
+
+**** Update =update(current: nil, indicator: nil, render: false)=
+You update the progress widget by calling =#update= on the Progress object,
+passing as the =current:= parameter a number that indicates progress so far.
+
+#+begin_src ruby :tangle no
+  #! /usr/bin/env -S ruby -Ilib
+  # -*- mode: ruby -*-
+
+  require 'fatty'
+  require 'prime'
+
+  primer = lambda do |input, fatty|
+    if input.match?(/\A[1-9]\d*\z/)
+      k = input.to_i
+      prog = fatty.add_progress(label: "Thinking...", total: k, style: :bar)
+      out_line = +""
+      num_primes = 0
+      Prime.each do |p|
+        num_primes += 1
+        out = "#{p} "
+
+        if out_line.length + out.length > 100
+          fatty.append_now("#{out_line}\n", mode: :scrolling)
+          out_line.clear
+        end
+
+        out_line << out
+        prog.update(current: num_primes)
+        break if num_primes >= k
+      end
+      fatty.append_now("#{out_line}\n", mode: :scrolling) unless out_line.empty?
+      prog.finish("Done")
+    else
+      fatty.alert "Give me a positive integer", role: :error
+    end
+  end
+
+  Fatty::Terminal.new(
+    on_accept: primer,
+    prompt: 'How many primes? ',
+  ).go
+#+end_src
+
+For the trail-style progress, you can use an arbitrary string to indicate
+progress by adding an =indicator:= parameter to the =#update= call.
+
+Suppose, for example, you wanted to print a trail in which the last digit of
+the prime is displayed to indicate progress and colored so it stands out:
+
+#+begin_src ruby :tangle no
+  #! /usr/bin/env -S ruby -Ilib
+  # -*- mode: ruby -*-
+
+  require 'fatty'
+  require 'prime'
+  require "rainbow/refinement"
+
+  using Rainbow
+
+  primer = lambda do |input, fatty|
+    if input.match?(/\A[1-9]\d*\z/)
+      k = input.to_i
+      prog = fatty.add_progress(label: "Thinking...", total: k, style: :trail, width: 100)
+      out_line = +""
+      num_primes = 0
+      Prime.each do |p|
+        num_primes += 1
+        out = "#{p} "
+
+        if out_line.length + out.length > 100
+          fatty.append_now("#{out_line}\n", mode: :scrolling)
+          out_line.clear
+        end
+
+        out_line << out
+        last_dig = p.to_s.split('').last
+        sig =
+          case last_dig
+          when '1'
+            last_dig.red
+          when '3'
+            last_dig.blue
+          when '7'
+            last_dig.green
+          when '9'
+            last_dig.yellow
+          else
+            '!'
+          end
+        prog.update(current: num_primes, indicator: sig)
+        break if num_primes >= k
+      end
+      fatty.append_now("#{out_line}\n", mode: :scrolling) unless out_line.empty?
+      prog.finish("Done")
+    else
+      fatty.alert "Give me a positive integer", role: :error
+    end
+  end
+
+  Fatty::Terminal.new(
+    on_accept: primer,
+    prompt: 'How many primes? ',
+  ).go
+#+end_src
+
+**** Finish
+As the prior examples illustrate, you can issue an ending message at the end
+of the process by calling =#finish= on the Progress object.
+
+**** Clear
+And, if you have occasion, you can clear the Progress by calling =#clear= on
+the Progress object.
+
+*** =choose(prompt, choices:, initial_choice_idx: 0, cancel_value: nil)=
+Present a set of =choices:=, which can be either:
+
+- an =Array= of =String= choices, where the selected string is returned; or
+- a =Hash= whose keys are converted to =String= labels and whose values are
+  returned.
+
+=choose= returns:
+
+- the selected =String= when =choices:= is an =Array=;
+- the associated value when =choices:= is a =Hash=; or
+- =cancel_value= when the user cancels with C-c or C-g.
+
+The =prompt= String (by default "Choose") can guide the user about the purpose
+of the choices.
+
+If you want to set one of the choices as the initial choice, set
+=initial_choice_idx:= to the Integer index of one of the choices.
+
+If you want a value associated with the user's cancellation of the chooser
+with C-c or C-g, set =cancel_value:= to that value.
+
+With an Array of Strings:
+
+#+begin_src ruby :tangle no
+#! /usr/bin/env -S ruby -Ilib
+# -*- mode: ruby -*-
+
+require 'fatty'
+
+rgb = lambda do |_line, fatty|
+  color = fatty.choose(
+    "Choose a color",
+    choices: ["red", "green", "blue"],
+  )
+  fatty.status("If you say so: #{Rainbow(color).send(color.to_sym)} it is!\n")
+end
+
+Fatty::Terminal.new(
+  prompt: "Hit RETURN to choose a color> ",
+  on_accept: rgb,
+).go
+#+end_src
+
+Or with a Hash:
+
+#+begin_src ruby :tangle no
+#! /usr/bin/env -S ruby -Ilib
+# -*- mode: ruby -*-
+
+require 'fatty'
+
+nums = lambda do |_line, fatty|
+  const = fatty.choose(
+    "Choose a constant",
+    choices: { "Pi" => 3.14159, "Euler" => 2.718281828, "Golden Ratio" => 1.61803398875 }
+  )
+  fatty.status("Somewhere around #{const}\n")
+end
+
+Fatty::Terminal.new(
+  prompt: "Hit RETURN to choose a constant> ",
+  on_accept: nums,
+).go
+#+end_src
+
+*** =choose_multi(prompt, choices:, cancel_value: nil)=
+Present a set of =choices:=, which can either be
+- an Array whose items are converted to =Strings= and presented as choices
+- a Hash whose keys converted to =Strings= and presented as choices
+
+=choose_multi= returns
+- a =Hash= whose keys and values are the user's
+  selections if =choices:= was an =Array= of =Strings=,
+- a =Hash= whose keys and values are those selected from the =choices:= =Hash=
+  if =choices:= was an =Hash=,
+- or the =cancel_value= if the user canceled the selection with C-c or C-g.
+
+The =prompt= String (by default "Choose Many") can guide the user about the purpose
+of the choices.
+
+*** =confirm(prompt, yes_label: "Yes", no_label: "No", cancel_value: false)=
+Present the user with a simple Yes/No choice using your choice of ways to
+express "Yes" or "No" with =yes_label:= and =no_label:=.
+
+=confirm= returns =true= for "Yes" and =false= for "No."
+
+=confirm= will return =false= on cancellation with C-c or C-g unless you
+provide an alternative =cancel_value:=, in which case it returns that.
+
+*** =menu(prompt, choices:, initial_choice_idx: 0, cancel_value: nil)=
+Present the user with a set of =choices:= representing actions to execute.
+
+=choices:= is a =Hash= whose keys are labels presented to the user and whose
+values are procs, lambdas, or other objects that respond to =#call=.
+
+#+begin_src ruby :tangle no
+  #! /usr/bin/env -S ruby -Ilib
+  # -*- mode: ruby -*-
+
+  require 'fatty'
+
+  asker = lambda do |_line, fatty|
+    result = fatty.menu(
+      "Pick an action",
+      choices: {
+        "Self Echo" => ->(fatty, label) {
+          fatty.append("You chose #{label}\n")
+          :echoed
+        },
+        "Say Hello" => ->(fatty, _label) {
+          name = fatty.prompt("Name?")
+          fatty.append("Hello, #{name}\n")
+          :greeted
+        },
+      },
+    )
+    fatty.good(result)
+  end
+
+  Fatty::Terminal.new(
+    on_accept: asker,
+    prompt: "Type RETURN for some action> ",
+  ).go
+#+end_src
+
+Each callable has access to the =CallbackEnvironment=, called =fatty= here and
+the =String= label that the user selected.
+
+Each callable can return a value that the =@on_accept= proc can process as it
+pleases.  In the example, they are printed to the status area.
+
+If you want to set one of the choices as the initial choice, set
+=initial_choice_idx:= to the Integer index of one of the choices.
+
+If you want a value associated with the user's cancellation of the chooser
+with C-c or C-g, set =cancel_value:= to that value.
+
+
+*** =environment=
+This returns a =Hash= of runtime conditions detected by =Fatty=:
+
+| Key                   | Description                                          |
+|-----------------------+------------------------------------------------------|
+| =:arch=               | System CPU architecture, e.g., =x86_64=              |
+| =:os=                 | Operating system detected                            |
+| =:ruby_platform=      | Ruby platform, e.g., =x86_64-linux=                  |
+| =:screen=             | Whether the terminal is running under =screen=       |
+| =:ssh=                | Whether the terminal is running under SSH            |
+| =:tmux=               | Whether the terminal is running under =tmux=         |
+| =:terminal=           | Detected underlying terminal, e.g., =kitty=          |
+| =:terminal_version=   | Version of the terminal, if known                    |
+| =:term=               | The =TERM= terminal type                             |
+| =:truecolor_detected= | Whether truecolor capability appears to be available |
+| =:truecolor_enabled=  | Whether Fatty is actually using truecolor rendering  |
+| =:curses=             | Runtime curses capabilities and parameters           |
+
+The environment report also includes a nested =:curses= hash:
+
+| Key                 | Description                                            |
+|---------------------+--------------------------------------------------------|
+| =:started=          | Whether curses has been initialized                    |
+| =:truecolor=        | Whether the active curses context is using truecolor   |
+| =:key_min=          | Lowest keycode with a curses name                      |
+| =:key_max=          | Highest keycode with a curses name                     |
+| =:lines=            | Number of terminal rows available                      |
+| =:cols=             | Number of terminal columns available                   |
+| =:has_colors=       | Whether curses reports color support                   |
+| =:colors=           | Number of colors available to curses                   |
+| =:color_pairs=      | Number of color pairs available to curses              |
+| =:can_change_color= | Whether curses can redefine color values               |
+
+* Default Interaction
+** Parts of the Screen
+*** Input Field
+Just above the bottom of the screen where all the action takes place: it is a
+line for editing the input.  It displays a prompt followed by an area in which
+you build the command line using =fatty's= editing facilities.
+
+*** Output Pane
+Most of the top part of the screen is reserved for displaying whatever output
+is sent to it with the =on_accept= callback to the =Terminal=.  It can render
+colored ANSI-encoded strings and will page long output so you can view it a
+page at a time and even search the output.
+
+*** Status Area
+The one to four lines just above the Input Field that displays output to the
+user that is out of band for the Output Pane.  Brief messages of confirmation,
+warning, or error can be displayed there so as to get the user's immediate
+attention.  Progress bars also render there where their visibility is made
+prominent.
+
+*** Alert Area
+Alerts are short-lived, non-scrolling messages shown below the input field.
+They are intended for user-visible conditions that require attention.  =Fatty=
+uses this area to warn the user of unrecognized key codes and of unbound key
+presses.
+
+** Command-line Editing
+=fatty= aims to have a full-featured command-line editor for editing a single
+line of text that is sent to the =on_accept= proc for the =Terminal=.  The
+default keybindings are based on Emacs keybindings, but they are fully
+customizable. Implementing =vim=-like keybindings is not currently possible
+because =fatty= has no notion of editing "modes" as would be required for any
+kind of a modal editor---at least not yet.  Maybe some day.
+
+*** Input Context
 When editing the input line or text input for widgets like the `prompt`,
 `fatty` provides emacs-like editing keybindings by default.  Many of these
 commands can take a count prefix argument to repeat the command count times.
 For example, `M-8 M-0 #` will insert 80 '#' characters at the cursor.
 
+**** Cursor Motion
+=Fatty= implements all the expected actions for moving the cursor around the
+input buffer.  You can move by characters or words or to the beginning or end
+of the buffer.
+
 | Key        | Description                                           |
 |------------+-------------------------------------------------------|
 | C-a        | move to the beginning of the line                     |
@@ -90,77 +859,1270 @@ For example, `M-8 M-0 #` will insert 80 '#' characters at the cursor.
 | M-b        | move cursor left one word                             |
 | M-:left    | move cursor left one word                             |
 | C-:left    | move cursor left one word                             |
-| C-t        | transpose characters                                  |
-| M-t        | transpose words                                       |
-|            |                                                       |
+
+
+**** Clearing
+This is one action that does not affect the input buffer but the output pane.
+It clears it.
+
+| Key        | Description                                           |
+|------------+-------------------------------------------------------|
+| C-l        | clear the output pane                                 |
+
+**** Undo and Redo
+=Fatty= keeps a stack of buffer-modifying actions, recording the buffer
+contents before any change is made.  The undo-redo facility allows you to
+traverse that stack, =undo= travels backward to an earlier buffer state, and,
+once at an earlier state, =redo= travels forward to a more recent buffer
+state.
+
+| Key        | Description                                           |
+|------------+-------------------------------------------------------|
+| C-/        | undo                                                  |
+| C-_        | undo                                                  |
+| C-M-/      | redo                                                  |
+| M-/        | redo                                                  |
+
+**** Deletion and Killing
+=Fatty= implements the emacs-esque notion of "killing" text by deleting it but
+also adding it to the "kill ring", a circular structure of all prior kills.
+It is circular in that successive "yanks", or pastes, traverse the kill ring
+and return to the beginning after reaching the end.  By contrast a "deletion"
+merely removes text from the buffer without adding it to the kill ring.
+
+When the region is active, destructive editing commands kill the region rather
+than deleting characters or words.
+
+| Key        | Description                                           |
+|------------+-------------------------------------------------------|
 | C-d        | delete character at cursor                            |
 | :delete    | delete character at cursor                            |
 | :backspace | delete character before cursor                        |
 | M-d        | kill word at cursor                                   |
 | C-w        | kill word before cursor                               |
 | C-k        | kill to end of line                                   |
-|            |                                                       |
-| C-/        | undo                                                  |
-| C-_        | undo                                                  |
-| C-M-/      | redo                                                  |
-| M-/        | redo                                                  |
-|            |                                                       |
-| C-:space   | set the mark at the current cursor position           |
-| C-@        | set the mark at the current cursor position           |
-| C-g        | clear the mark                                        |
-| C-w        | kill the region                                       |
-| M-w        | copy the region                                       |
-|            |                                                       |
-| C-y        | yank last kill at cursor                              |
-| M-y        | replace last yank with next in kill ring              |
-|            |                                                       |
-| C-u        | universal count argument (time 4 each press)          |
-| M-<digit>  | accumulate count argument                             |
-|            |                                                       |
+| C-t        | transpose characters                                  |
+| M-t        | transpose words                                       |
+
+**** Yanking, Mark, and Region
+Text that has been killed can be "yanked" into the buffer at the cursor
+position with the "yank" action.  That text can be replaced by successive
+entries in the kill ring with the yank_pop action.
+
+In addition, =fatty= allows you to define a "region" by setting a mark and
+moving the cursor.  The text between the mark and the cursor is the region.
+The region can be killed or copied, that is deleted and added to the kill ring or
+just added to the kill ring.
+
+Notice that commands that normally delete characters or words, kill the region
+if the region is active.
+
+| Key        | Description                                       |
+|------------+---------------------------------------------------|
+| C-y        | yank last kill at the cursor                      |
+| M-y        | replace last yank with next item in the kill ring |
+|            |                                                   |
+| C-d        | when region active, kill the region               |
+| :delete    | when region active, kill the region               |
+| :backspace | when region active, kill the region               |
+| M-d        | when region active, kill the region               |
+| C-w        | when region active, kill the region               |
+|            |                                                   |
+| C-:space   | set the mark at the current cursor position       |
+| C-@        | set the mark at the current cursor position       |
+| C-g        | clear the mark                                    |
+| C-w        | kill the region                                   |
+| M-w        | copy the region                                   |
+
+**** Count Prefix
+By default each action acts on one item, so the default count is 1.  But for
+certain commands that operate on characters or words, you can modify the count
+by typing =M-<digit>= keys before the command.  For example, if you want to
+insert exactly 80 '#' characters into the buffer, =M-8 M-0 #= will do the
+trick.
+
+There is one command, however, for which the count is not used as a repeat
+count: for =page_top= (bound in paging to =g=) the count is used as a line
+number to navigate to.
+
+Fatty follows the emacs convention of making =C-u= multiply the count prefix
+by 4 with each press.  So you can insert 64 '#' characters with =C-u C-u C-u
+#=.
+
+| Key       | Description                                        |
+|-----------+----------------------------------------------------|
+| C-u       | universal count argument (times 4 with each press) |
+| M-<digit> | accumulate a count argument                        |
+
+
+**** History Navigation
+=Fatty= sports a rather sophisticated history system.  It not only records
+each completed item of input but can also be made to note the kind of items
+and the "context" in which it was entered.
+
+History is essentially partitioned into separate "kinds" of history so that
+the command line can occupy one part of history and search strings a different
+part of history.  That way, the history is made relevant to the current input
+buffer that you are working on.
+
+In addition, each history item can note its "context".  This is less strict
+than "kinds" of history but allows the history mechanism to favor history
+items from the same "context" as the current context.  For example, in the
+=fatty= demo, any line that is not a builtin command is treated as a shell
+
+if you traverse history items, you will be shown command executed from the
+directory you are in before other history items.  It still will give you items
+from other contexts, it just pushes items from the current context to the
+front of the list.
+
+You can navigate history items with the =up= and =down= keys as you would
+expect.  But you can also have the history items presented in a popup that
+shows all history items then allows you to narrow the items displayed by
+typing text into its narrowing input field.  Bonus: the narrowing input field
+itself has a history that you can access with =M-p= and =M-n=.  History on
+history.
+
+| Key        | Description                                           |
+|------------+-------------------------------------------------------|
 | C-p        | replace the line with the prior history item          |
 | :up        | replace the line with the prior history item          |
 | C-n        | replace the line with the next history item           |
-| :down      | replace the line with the prior history item          |
+| :down      | replace the line with the next history item           |
 | C-r        | search the history in a popup                         |
-|            |                                                       |
-| :enter     | feed the line to the on_accept proc and page output   |
-| M-:enter   | feed the line to the on_accept proc and scroll output |
-| C-c        | quit `fatty`                                          |
-| C-d        | quit `fatty` only if the input line is empty          |
-| C-l        | clear the output pane                                 |
-|            |                                                       |
 
+**** Completion
+=Fatty= also provides a completion facility that makes entering input easier.
+***** Input Completion
+As you type a command-line, =fatty= will auto-suggest ways to complete the
+line with dimmed text to the right of the cursor:
+
+#+CAPTION: Input editing showing region and predictive completion.
+#+ATTR_HTML: :alt Fatty command line screenshot :width 900
+
+[[file:images/auto_suggest.png]]
+
+After typing 'ec' =fatty= suggests a command-line pulled from history using
+the dimmed text to the right of the cursor.  The suggestion can be accepted by
+moving the cursor into the suggestion, and any text then to the left of the
+cursor becomes part of the input buffer.
+
+=fatty= may have several completions suggested by the text-so-far and you can
+cycle through them by hitting the =tab= key.  And if you want, you can see all
+the suggestions in a popup with =M-tab=.  That allows narrowing by the text of
+the completions and the narrowing filter has its own history.
+
+#+CAPTION: Completion popup with narrowing.
+#+ATTR_HTML: :alt Fatty command line screenshot :width 900
+
+[[file:images/completion_popup.png]]
+
+***** Sources for Input Completion
+For input completion, =fatty= uses two sources:
+
+1. The input history.
+2. The candidates returned by the =Terminal#completion_proc=.
+
+History completion is always available when the terminal has history enabled.
+It lets the user complete from lines they have previously accepted.  This is
+especially useful for command shells, REPL-style interfaces, and applications
+where users often repeat or slightly modify earlier input.
+
+Application completion is supplied by the optional =completion_proc= passed to
+=Fatty::Terminal.new=.  The proc is called with the input buffer's text-so-far
+and returns candidate strings.  This is where an application can offer
+completions for commands, file names, account names, option names, object
+identifiers, or anything else meaningful to the application.
+
+The two sources are combined before they are presented to the user.  Fatty
+deduplicates candidates and then offers the result through the normal completion
+interface.  =TAB= cycles through completions inline.  =M-TAB= opens a completion
+popup, where the user can narrow the candidate list by typing in the
+=Complete:= field.
+
+Application candidates are offered first.  History candidates fill in behind
+them.  This gives the host application priority for current, domain-specific
+completions while still letting users recover earlier accepted input.
+
+The completion popup is still a popup filter.  Its narrowing text has its own
+history, separate from command input history and from other popup filters.  Use
+=M-p= and =M-n= inside the completion popup to recall previous completion
+filters.
+
+***** File Name Completion
+Apart from command-line completion, =fatty= offers completion of file names if
+the cursor is at the end of a string that looks like a file name: that is, it
+starts with './', '../', '~/' or '/'.
+
+1. If the string-so-far matches only one directory or file name, it inserts
+   that into the input buffer and continues completion from there.
+2. If the string-so-far matches multiple files or directories it auto-suggests
+   the first and =TAB= cycles through each of the candidates which you can
+   accept by moving the cursor past the suggestion.  Likewise =S-TAB= cycles
+   backwards through the list of candidates.
+3. If the string-so-far matches no files, completion does nothing.
+
+Just as with command line completion, you can invoke a popup of completions
+with =M-TAB= and a popup of possible file names will appear within which you
+may filter the candidates down by narrowing.  Unlike other forms of
+completion, the file name completion popup allows you to fill out the path by
+navigating directories within the popup by hitting =TAB= or =right= to descend
+into a sub-directory or =S-TAB= or =left= to ascend to the parent directory.
+The popup title shows the path so far.
+
+**** Accept or Cancel
+Finally, when the command-line is to your satisfaction, you can submit the
+line to the =on_accept= proc which determines how your app responds to it.
+
+You can end a =fatty= session with =C-c= at the command line, or (only if the
+buffer is empty) with =C-d=.
+
+| Key      | Description                                           |
+|----------+-------------------------------------------------------|
+| :enter   | feed the line to the on_accept proc and page output   |
+| M-:enter | feed the line to the on_accept proc and scroll output |
+| C-c      | quit `fatty`                                          |
+| C-d      | quit `fatty` only if the input line is empty          |
 
 *** Paging Context
+Once the command-line is accepted, `fatty` sends output to the large output
+pane, and if the output is more than one screen long presents a paging
+environment for viewing and searching the output.  From there, =fatty= offers
+the expected navigation aids for examining the output:
 
-By default, `fatty` sends output to the large output pane, and if the output
-is more than one screen long presents a paging environment for viewing and
-searching the environment.
+| Key         | Count? | Description                                         |
+|-------------+--------+-----------------------------------------------------|
+| =up=        | Yes    | move output one line up                             |
+| =k=         | Yes    | move output one line up                             |
+| =down=      | Yes    | move output one line down                           |
+| =j=         | Yes    | move output one line down                           |
+| =page_up=   | Yes    | move back one page                                  |
+| =b=         | Yes    | move back one page                                  |
+| =u=         | Yes    | move back one page                                  |
+| =M-v=       | Yes    | move back one page                                  |
+| =backspace= | Yes    | move back one page                                  |
+| =page_down= | Yes    | move forward one page                               |
+| =f=         | Yes    | move forward one page                               |
+| =d=         | Yes    | move forward one page                               |
+| =space=     | Yes    | move forward one page                               |
+| =C-v=       | Yes    | move forward one page                               |
+| =home=      | No     | move to the top of output                           |
+| =M-<=       | No     | move to the top of output                           |
+| =g=         | Yes    | move to the top, or to the counted original line*   |
+| =end=       | No     | move to the end of output                           |
+| =M->=       | No     | move to the end of output                           |
+| =G=         | No     | move to the end of output                           |
+| ~=~         | No     | toggle the display of line numbers                  |
+| =M-s=       | No     | toggle between paging and scrolling                 |
+| =/=         | No     | initiate a fixed-string search forward              |
+| =?=         | No     | initiate a fixed-string search backward             |
+| =C-s=       | No     | initiate an Isearch session forward                 |
+| =C-r=       | No     | initiate an Isearch session backward                |
+| =C-M-s=     | No     | initiate an Regexp session forward                  |
+| =C-M-r=     | No     | initiate an Regexp session backward                 |
+| =C-/=       | No     | initiate an Regexp session forward                  |
+| =<=         | No     | narrow output to lines containing all entered terms |
+| =>=         | No     | widen output by clearing the narrowing              |
+| =C-c=       | No     | quit paging                                         |
+| =q=         | No     | quit paging                                         |
+| =C-g=       | No     | quit paging                                         |
+| =escape=    | No     | quit paging                                         |
+| =n=         | Yes    | move to the next instance of the current search     |
+| =N=         | Yes    | move to the prior instance of the current search    |
 
-| Key   | Description               |
-|-------+---------------------------|
-| :up   | move output one line up   |
-| k     | move output one line up   |
-| :down | move output one line down |
-| j     | move output one line down |
-|       |                           |
+=*= Without a count, =g= moves to the beginning of output.  With a numeric
+prefix, it moves to that original output line; for example, =M-1 M-0 M-0 M-0
+g= moves to line 1000.  It uses the original line numbers even when output is
+narrowed.
 
+As you can see, =fatty= tries to accommodate a number of finger habits besides
+=emacs=, including =vim= and =Emacs Info=, by offering several alternative
+ways to invoke navigation actions.
 
-* Alerts
-Alerts are short-lived, non-scrolling messages shown below the input line.
-They are intended for user-visible conditions that require attention.
+One unusual action is invoked by =M-s= which toggles the output between
+scrolling mode without pause and paging mode.  It can be invoked while doing
+either to enter the other mode.
 
-* Markdown
-** Forced line breaks
-Use ~<br>~ to force a line break.
+You can add line numbers to the display while paging by using the ~=~ key.
 
-#+begin_example
-This line has a forced line break <br> and this should appear on the next line.
-#+end_example
+You can also "narrow" the output with =<=, which will prompt you for one or
+more terms to match.  The output will then show only lines that match all the
+terms typed.  To return to the full output, "widen" with =>=.
 
-will render as
+*** Searching Output
+While paging, you can initiate a search of the output as indicated in the
+above key bindings for paging.  Once a search session is initiated, =fatty=
+presents an input line for entering search terms.
 
-#+begin_example
-This line has a forced line break
-and this should appear on the next line.
-#+end_example
+After a search session has ended, =fatty= returns to paging but remembers the
+last search term and allows navigation among them with =n= and =N=: =n=
+searches in the direction of the last search and =N= searches in the opposite
+direction.  Notice that the current search term and direction are added to the
+paging bar after the information on your location within the output.
+
+**** String and Regex Search
+=/= and =?= prompt for a fixed string and search forward or backward.  =C-M-s=
+(or =C-/=) and =C-M-r= (or =C-?=) perform the corresponding regular-expression
+searches.  Accepting the search leaves the selected match active for later
+navigation with =n= and =N=.
+
+**** Incremental Search
+=C-s= and =C-r= begin forward or backward incremental search.  The output
+moves to matching text as the search term is edited.  Accepting commits the
+match; canceling restores the output position from before the search began.
+
+
+* Configuration
+When a Fatty application starts, Fatty installs default configuration files
+under =~/.config/fatty= if they do not already exist.  Fatty does not overwrite
+files that are already there, so you can edit these files directly and keep
+them under version control.
+
+The config files are:
+
+- =config.yml= :: general configuration;
+- =keydefs.yml= :: terminal-specific keycode naming;
+- =keybindings.yml= :: user-defined keybindings;
+- =themes/= :: YAML theme files.
+
+The default user-specific configuration directory follows =XDG_CONFIG_HOME= if
+it is set.  Otherwise it is =~/.config/fatty=.
+
+In addition to the user-specific configuration, fatty will read app-specific
+configuration files from =~/.config/fatty/apps/<app_name>= if =Terminal= was
+given an =app_name= parameter.  It will use a different directory of your
+choosing if =Terminal= was given an =app_config_dir= directory name.
+
+** General Configuration =config.yml=
+
+=config.yml= controls general behavior such as word movement, ESC handling,
+logging, history, the initial theme, and truecolor rendering.
+
+A small configuration might look like this:
+
+#+begin_src yaml :tangle no
+word_char_re: "[[:alnum:]_.:-]"
+
+esc_delay: 0
+
+history:
+  file: "~/.fatty_history"
+  max: 10000
+
+theme: wordperfect
+
+truecolor: auto
+#+end_src
+
+*** =word_char_re=
+This setting is a Ruby regular expression fragment used to decide what counts
+as a word in the input buffer.  It must be a =String= representing a =Regexp=
+that matches a single character that is meant to be a part of a "word" for
+purposes of cursor movement.  The default setting treats letters, digits, and
+underscore as word characters:
+
+#+begin_src yaml :tangle no
+word_char_re: "[[:alnum:]_]"
+#+end_src
+
+For command-line applications, you may want dashes to be part of a word:
+
+#+begin_src yaml :tangle no
+word_char_re: "[[:alnum:]_-]"
+#+end_src
+
+For Ruby constants, hostnames, or command-like tokens, you may want a broader
+definition:
+
+#+begin_src yaml :tangle no
+word_char_re: "[[:alnum:]_.:-]"
+#+end_src
+
+*** =esc_delay=
+=esc_delay= controls how long curses waits after receiving =ESC= before
+deciding whether another key is part of the same Meta-key sequence.  The value
+is in milliseconds.
+
+#+begin_src yaml :tangle no
+esc_delay: 0
+#+end_src
+
+
+*** =history=
+**** =file=
+The path to the history file to use, by default =~/.fatty_history=
+
+**** =max=
+The maximum number of lines of history retained, by default 10,000.
+
+*** =theme=
+The =theme= setting names the theme Fatty applies at startup:
+
+#+begin_src yaml :tangle no
+theme: nordic
+#+end_src
+
+*** =truecolor=
+The =truecolor= setting controls whether Fatty uses truecolor escape sequences
+for rendering colors.  The usual setting is =auto=, meaning that =truecolor=
+is enabled if available.  It can be set to =true=, =false=, =on=, =off= or
+=auto=.
+
+#+begin_src yaml :tangle no
+truecolor: auto
+#+end_src
+
+*** =log=
+Logging is configured under =log=:
+
+#+begin_src yaml :tangle no
+    log:
+    file: "~/log/fatty.log"
+    level: debug
+    tags:
+      - keycode
+      - keyevent
+      - keybinding
+      - action
+      - command
+      - session
+      - render
+      - perf
+#+end_src
+
+**** =file=
+The path to the log file to use.
+
+**** =level=
+Can be one of the following
+- =info= :: only informational messages
+- =warn= :: only non-fatal warning messages and =info= messages
+- =error= :: only fatal error messages and =warn= and =info= messages
+- =debug= :: detailed messages to assist debugging =fatty= plus all of the
+  above.
+
+**** =tags=
+
+=log.tags= controls which tagged log messages are written.  Tags are ordinary
+symbolic labels used by Fatty's logging calls; they are not checked against a
+fixed registry.  A tag is useful if Fatty logs messages with that tag.
+
+The special tag =all= enables all tagged log messages except =perf=.
+Performance logging is intentionally noisy and must be enabled explicitly with
+=perf=.
+
+#+begin_src yaml :tangle no
+log:
+tags:
+- keycode
+- keybinding
+- render
+- perf
+#+end_src
+
+** Key code definitions =keydefs.yml=
+Most keys are named correctly by curses.  Some terminal emulators, multiplexers,
+or keyboard modes emit numeric keycodes that curses does not name usefully.
+The =keydefs.yml= file lets you assign names and modifiers to those numeric
+codes.
+
+When Fatty runs inside =tmux=, key definitions are looked up under =tmux=, not
+under the outer terminal emulator.  =tmux= translates the outer terminal's input
+before Fatty sees it, so keycodes observed inside =tmux= may differ from
+keycodes observed directly under GNOME Terminal, Kitty, Alacritty, or another
+terminal.  Use =keytest= in the same environment where the application will
+normally run.  The same comment applies to =screen=.
+
+A key definition is terminal-specific.  For example:
+
+#+begin_src yaml :tangle no
+  tmux:
+    555:
+      key: left
+      meta: true
+    570:
+      key: right
+      meta: true
+    557:
+      key: left
+      ctrl: true
+    572:
+      key: right
+      ctrl: true
+#+end_src
+
+This says that, when Fatty detects that the terminal is =tmux=, curses keycode
+=555= should be treated as =M-left=, keycode =570= as =M-right=, and so on.
+
+The demo executable has a =keytest= command that is useful when building this
+file.  Run =fatty=, use the =keytest= command, press the key you want to
+identify, and add an entry for the numeric code if Fatty does not already know
+what to call it.
+
+Here is what I found running =keytest= on a variety of popular terminals to
+determine how each reported =PageDown=, =C-PageDown=, =M-PageDown=, and
+=C-M-PageDown=:
+
+| Terminal       | Key Pressed | Ctrl? | Meta? |   Code | Status            |
+|----------------+-------------+-------+-------+--------+-------------------|
+| gnome-terminal | PageDown    | no    | no    |    338 | Defined and bound |
+| gnome-terminal | PageDown    | yes   | no    |    559 | Undefined         |
+| gnome-terminal | PageDown    | no    | yes   |    557 | Undefined         |
+| gnome-terminal | PageDown    | yes   | yes   |    561 | Undefined         |
+|----------------+-------------+-------+-------+--------+-------------------|
+| alacritty      | PageDown    | no    | no    |    338 | Defined and bound |
+| alacritty      | PageDown    | yes   | no    |    559 | Undefined         |
+| alacritty      | PageDown    | no    | yes   |    557 | Undefined         |
+| alacritty      | PageDown    | yes   | yes   |    561 | Undefined         |
+|----------------+-------------+-------+-------+--------+-------------------|
+| kitty          | PageDown    | no    | no    |    338 | Defined and bound |
+| kitty          | PageDown    | yes   | no    |    565 | Undefined         |
+| kitty          | PageDown    | no    | yes   |    563 | Undefined         |
+| kitty          | PageDown    | yes   | yes   |    567 | Undefined         |
+|----------------+-------------+-------+-------+--------+-------------------|
+| terminator     | PageDown    | no    | no    |    338 | Defined and bound |
+| terminator     | PageDown    | yes   | no    | <none> | Undefinable       |
+| terminator     | PageDown    | no    | yes   |    557 | Undefined         |
+| terminator     | PageDown    | yes   | yes   |    561 | Undefined         |
+|----------------+-------------+-------+-------+--------+-------------------|
+| ghostty        | PageDown    | no    | no    |    338 | Defined and bound |
+| ghostty        | PageDown    | yes   | no    |    564 | Undefined         |
+| ghostty        | PageDown    | no    | yes   |    562 | Undefined         |
+| ghostty        | PageDown    | yes   | yes   |    566 | Undefined         |
+|----------------+-------------+-------+-------+--------+-------------------|
+| konsole        | PageDown    | no    | no    |    338 | Defined and bound |
+| konsole        | PageDown    | yes   | no    |    559 | Undefined         |
+| konsole        | PageDown    | no    | yes   |    557 | Undefined         |
+| konsole        | PageDown    | yes   | yes   |    561 | Undefined         |
+
+I could turn this into a =keydefs.yml= file that would allow me to define all
+those keys:
+
+#+begin_src yaml :tangle no
+  gnome-terminal:
+    559:
+      key: page_down
+      ctrl: true
+    557:
+      key: page_down
+      meta: true
+    561:
+      key: page_down
+      ctrl: true
+      meta: true
+
+  alacritty:
+    559:
+      key: page_down
+      ctrl: true
+    557:
+      key: page_down
+      meta: true
+    561:
+      key: page_down
+      ctrl: true
+      meta: true
+
+  kitty:
+    565:
+      key: page_down
+      ctrl: true
+    563:
+      key: page_down
+      meta: true
+    567:
+      key: page_down
+      ctrl: true
+      meta: true
+
+  terminator:
+    # 559:
+    #   key: page_down
+    #   ctrl: true
+    557:
+      key: page_down
+      meta: true
+    561:
+      key: page_down
+      ctrl: true
+      meta: true
+
+  ghostty:
+    564:
+      key: page_down
+      ctrl: true
+    562:
+      key: page_down
+      meta: true
+    566:
+      key: page_down
+      ctrl: true
+      meta: true
+
+  konsole:
+    559:
+      key: page_down
+      ctrl: true
+    557:
+      key: page_down
+      meta: true
+    561:
+      key: page_down
+      ctrl: true
+      meta: true
+#+end_src
+
+After installing that keydefs, I find that the PageDown variants are all
+recognized by name and modifiers (except for the strange failure of
+=terminator= to recognize =C-PageDown=!).
+
+** Key bindings  =keybindings.yml=
+Fatty has built-in Emacs-style bindings for ordinary input editing, history,
+completion, popup navigation, and paging.  The =keybindings.yml= file lets you
+add or override bindings without changing Ruby code.
+
+A keybinding names a key chord, the context in which it applies, and the Fatty
+action to run:
+
+#+begin_src yaml :tangle no
+- key: left
+  meta: true
+  action: move_word_left
+
+- key: right
+  meta: true
+  action: move_word_right
+
+- key: space
+  context: paging
+  action: page_down
+
+- key: backspace
+  context: paging
+  action: page_up
+  #+end_src
+
+*** Key Names
+A keybinding uses the unmodified key name under the =key= field:
+#+begin_src yaml :tangle no
+- key: f
+  meta: true
+  context: text
+  action: move_word_right
+  #+end_src
+
+**** Printable Keys
+Most printable keys can be written as the character itself.  Quote keys that
+YAML might otherwise treat specially or make hard to read, such as =":"=,
+="#"=, ="["=, ="]"=, ="{"=, ="}"=, ="\""=, and ="\\"=.
+#+begin_src yaml :tangle no
+  - key: a
+  - key: /
+  - key: .
+  - key: =
+  - key: "\\"
+  - key: "\""
+#+end_src
+
+**** Curses and Fatty Named Keys
+=Fatty= translates codes returned by curses for special keys into names:
+|                |                |                 |                   |                |
+|----------------+----------------+-----------------+-------------------+----------------|
+| =tab=          | =insert=       | =delete=        | =home=            | =end=          |
+| =left=         | =right=        | =page_up=       | =page_down=       | =up=           |
+| =down=         | =f1=           | =f2=            | =f3=              | =f4=           |
+| =f8=           | =f9=           | =f10=           | =f11=             | =f12=          |
+| =keypad_0=     | =keypad_1=     | =keypad_2=      | =keypad_3=        | =keypad_4=     |
+| =keypad_8=     | =keypad_9=     | =keypad_divide= | =keypad_multiply= | =keypad_minus= |
+| =keypad_enter= | =keypad_comma= |                 |                   |                |
+
+Some terminals can report application-keypad sequences such as
+=keypad_divide=, =keypad_multiply=, or =keypad_enter=, but numeric keypad
+digits are often not distinguishable from ordinary digits when NumLock is on,
+and are often reported as navigation keys such as =end=, =down=, =page_down=,
+or =left= when NumLock is off.  Use =keytest= to see what your terminal
+actually sends.
+
+=Fatty= also provides convenient names to other common keys:
+
+- =enter=,
+- =escape=, and
+- =space=
+
+**** Possibly Invisible Keys
+Some physical keys may never reach Fatty at all.  They may be handled by the
+keyboard firmware, the kernel, the desktop environment, the window manager, or
+the terminal emulator before curses can report them.  Common examples include
+=Print Screen=, =Scroll Lock=, =Pause/Break=, =Caps Lock=, =Num Lock=, =Fn=,
+=Menu/Application=, =Super/Windows=, power/sleep/wake keys, brightness keys,
+volume/media keys, keyboard-backlight keys, airplane-mode keys, and touchpad
+toggle keys.
+
+Use =keytest= to check.  If Fatty sees a key as a raw numeric code, you can
+name it in =keydefs.yml= and bind it.  If =keytest= shows nothing, the key is
+being intercepted before Fatty receives it.
+
+**** Unnamed but Recognized Keys
+Some terminals report modified special keys as distinct numeric keycodes that
+=fatty= and =curses= do not name.  Use =keytest= to discover those codes, then
+assign names to them in =keydefs.yml=.  The name can be one of Fatty's usual
+names, or a new name of your own.
+
+For example, if a keyboard has an extra thumb key and =keytest= reports it as
+an uncoded keycode =601=, you could name it:
+
+#+begin_src yaml :tangle no
+gnome-terminal:
+  601:
+    key: thumb_left
+#+end_src
+
+Then bind it in =keybindings.yml=:
+
+#+begin_src yaml :tangle no
+- key: thumb_left
+  context: text
+  action: move_word_left
+  #+end_src
+
+Fatty does not require custom key names to come from a fixed registry.  A
+custom name only needs to be used consistently between =keydefs.yml= and
+=keybindings.yml=.
+
+*** Mouse Events
+Mouse events can also be bound:
+
+#+begin_src yaml :tangle no
+- button: left_clicked
+  context: popup
+  action: choose
+#+end_src
+
+Recognized mouse button names include:
+
+#+begin_src org :tangle no
+  left_pressed
+  left_released
+  left_clicked
+  left_double_clicked
+  left_triple_clicked
+  middle_pressed
+  middle_released
+  middle_clicked
+  middle_double_clicked
+  middle_triple_clicked
+  right_pressed
+  right_released
+  right_clicked
+  right_double_clicked
+  right_triple_clicked
+  scroll_up
+  scroll_down
+#+end_src
+
+*** Modifiers
+A binding may include these modifiers:
+
+#+begin_src yaml :tangle no
+ctrl: true
+meta: true
+shift: true
+#+end_src
+
+*** Contexts
+In =Fatty=, the key map is partitioned by "contexts" and in different
+environments the contexts are tried in order from highest priority to lowest
+and the first binding found wins. The following table lists the contexts
+associated with each interaction environment:
+
+| Environment        | Contexts High to Low                   |
+|--------------------+----------------------------------------|
+| Input Field        | :input, :text, :terminal               |
+| Output Paging      | :paging, :terminal                     |
+| Output Scrolling   | :terminal                              |
+| String Search      | :search, :text, :terminal              |
+| Incremental Search | :isearch, :text, :terminal             |
+| Prompt Popup       | :prompt, :text, :terminal              |
+| Popup Choose       | :popup, :text, :terminal               |
+| Popup Multi-Choose | :popup_multi, :popup, :text, :terminal |
+
+The available contexts are:
+
+| Context        | Meaning                                               |
+|----------------+-------------------------------------------------------|
+| =:terminal=    | global terminal/session commands                      |
+| =:text=        | ordinary text-editing commands shared by input fields |
+| =:input=       | the main command input field                          |
+| =:paging=      | output pager navigation                               |
+| =:search=      | non-incremental search field                          |
+| =:isearch=     | incremental search field                              |
+| =:prompt=      | prompt popup input                                    |
+| =:popup=       | popup selection/navigation                            |
+| =:popup_multi= | multi-select popup behavior                           |
+
+The `:terminal` context is the lowest-priority fallback context for
+terminal-wide commands. It is where Fatty puts bindings that are not specific
+to text editing, paging, search, or popup selection, such as theme selection,
+key testing, and quitting. Because `:terminal` is searched last, any more
+specific context can override a terminal-wide binding.
+
+*** Actions
+A keybinding connects a key event in a context to an "action." An action is a
+named Fatty command such as `move_left`, `delete_backward`, `accept_line`,
+`page_down`, `choose_theme`, or `quit`.
+
+A binding entry names the action with the `action` field:
+
+#+begin_src yaml :tangle no
+- key: left
+  context: text
+  action: move_left
+
+- key: f
+  meta: true
+  context: text
+  action: move_word_right
+
+- key: page_down
+  context: paging
+  action: page_down
+#+end_src
+
+Most movement, deletion, history, completion, paging, and popup-navigation
+actions honor Fatty's numeric count argument. The count is entered before the
+command, Emacs-style. For example, =M-5 C-f= moves forward five characters if
+=C-f= is bound to move_right, and =M-3 C-n= moves down three items if =C-n= is
+bound to the current environment's =next-item= action.
+
+Use `keytest` to check what action is currently bound to a key. If a key is
+bound, `keytest` reports the matching context, action name, arguments, and the
+object that handles the action.
+
+**** Input buffer actions
+Input buffer actions edit the contents of a text buffer. These are the ordinary
+line-editing operations shared by the main input field, search fields, prompt
+popups, and other text-like interactions. Many of these actions honor the
+numeric prefix count.
+
+Terminology notes:
+- kill ring :: like emacs, =fatty= keeps a "clipboard" of items with the
+  newest item in the current position and older items "before" it but in a
+  "ring" that return to the beginning;
+- yank :: retrieve the most recent item from the kill ring
+- yank pop :: retrieve successively older items from the kill ring
+- delete :: removes text without copying it to the kill ring;
+- kill :: removes text and copies it to the kill ring for later yank;
+- word :: a sequence of contiguous characters that are each matched by the
+  =word_char_re= from the config file or "[[:alnum]_]" by default;
+
+| Action Name          | Count? | Description                                |
+|----------------------+--------+--------------------------------------------|
+| bol                  | No     | Move cursor to beginning of buffer         |
+| clear                | No     | Clear the buffer                           |
+| clear_mark           | No     | Clear the region mark                      |
+| copy_region          | No     | Copy the text in the region to kill ring   |
+| delete_char_backward | Yes    | Delete char to the left of cursor          |
+| delete_char_forward  | Yes    | Delete char to the right of cursor         |
+| delete_region        | No     | Delete the text in the region              |
+| eol                  | No     | Move cursor to end of buffer               |
+| kill_region          | No     | Kill the text in the region                |
+| kill_to_bol          | No     | Kill the text from cursor to beginning     |
+| kill_to_eol          | No     | Kill the text from cursor to end           |
+| kill_word_backward   | Yes    | Kill the word to the left of  cursor       |
+| kill_word_forward    | Yes    | Kill the word to the right of  cursor      |
+| move_left            | Yes    | Move cursor one char left                  |
+| move_right           | Yes    | Move cursor one char right                 |
+| move_word_left       | Yes    | Move cursor one word left                  |
+| move_word_right      | Yes    | Move cursor one word right                 |
+| redo                 | No     | Redo an undone action                      |
+| set_mark             | No     | Set the region mark at cursor              |
+| transpose_chars      | Yes    | Switch position of char with prior char    |
+| transpose_words      | Yes    | Switch position of word with prior char    |
+| undo                 | No     | Revert last edit action                    |
+| yank                 | No     | Copy kill ring to buffer at cursor         |
+| yank_pop             | Yes    | Copy next kill ring item and replace prior |
+
+**** Input field actions
+Input field actions operate on an editable input field. An input field occurs
+at the main input prompt, but also in things like search-narrowing input,
+incremental-search, a prompt for text, etc.  It is lower level than the shell
+session input described in the next section.  In particular, it can have its
+own history attached to it depending on its purpose.  They handle accepting
+the current line, moving through history, and receiving pasted text.
+
+| Action Name  | Count? | Description                                               |
+|--------------+--------+-----------------------------------------------------------|
+| accept_line  | No     | Accept the current text as the input                      |
+| history_prev | No     | Insert the prior relevant history item in the input field |
+| history_next | No     | Insert the next relevant history item in the input field  |
+
+**** Shell session actions
+Shell session actions operate at the session level around the main command
+input and output area. They submit input, interrupt running work, clear output,
+start completion, open completion/history popups, and manage numeric prefix
+entry.
+
+| Action Name        | Count? | Description                                                      |
+|--------------------+--------+------------------------------------------------------------------|
+| submit_line        | No     | Pass the current text to the on_accept proc and page output      |
+| submit_and_scroll  | No     | Pass the current text to the on_accept proc and scroll output    |
+| interrupt          | No     | End the current session                                          |
+| interrupt_if_empty | No     | End the current session only if the current text is empty        |
+| clear_output       | No     | Clear the output pane                                            |
+| complete           | No     | Suggest the next possible completion as an autosuggestion        |
+| complete_previous  | No     | Suggest the prior possible completion as an autosuggestion       |
+| completion_popup   | No     | Display all possible completions in a popup for selection        |
+| history_search     | No     | Display history item starting with the text-so-far for selection |
+| count_digit        | No     | Add a digit to the numeric prefix                                |
+| universal_argument | No     | Set the numeric argument to 4 or multiply the current one by 4   |
+
+**** Pager actions
+Pager actions navigate output when the output area is in paging mode. They move
+by line, page, top, bottom, or end of output, handle mouse-wheel scrolling, and
+switch between paging and scrolling behavior. Most movement actions honor the
+numeric prefix count.
+
+| Action Name         | Count? | Description                                      |
+|---------------------+--------+--------------------------------------------------|
+| page_up             | Yes    | Move the output view one page up                 |
+| page_down           | Yes    | Move the output view one page down               |
+| end_of_output       | No     | Move the output to the end of output and scroll  |
+| line_up             | Yes    | Move the output view one line up                 |
+| line_down           | Yes    | Move the output view one line down               |
+| scroll_up           | Yes    | Move the output view six lines up                |
+| scroll_down         | Yes    | Move the output view six lines down              |
+| page_top            | Yes    | Move to the beginning, or to the counted line    |
+| page_bottom         | No     | Move the output to the end of output             |
+| paging_to_scrolling | No     | Quit paging and scroll output as it is produced  |
+| toggle_paging       | No     | Toggle output mode between paging and scrolling  |
+| quit_paging         | No     | Quit paging and return control to the input line |
+
+**** Pager search actions
+
+Pager search actions can /initiate/ a search session within the pager: a
+string search, a regular expression search, or an incremental-search.  Once a
+search session is entered, other actions navigate matches in the output.
+There are also actions to end a search session.
+
+While the search session is active, accepting commits the current match and
+canceling restores the pager to the position it had when the search began.
+After the search is accepted, =n= and =N= repeat the committed search in the
+pager; at that point the search session is no longer active.
+
+| Action Name                 | Count? | Description                                                         |
+|-----------------------------+--------+---------------------------------------------------------------------|
+| pager_search_forward        | No     | Initiate a string search forward from current output point          |
+| pager_search_backward       | No     | Initiate a string search backward from current output point         |
+| pager_regex_search_forward  | No     | Initiate a regex search forward from current output point           |
+| pager_regex_search_backward | No     | Initiate a regex search backward from current output point          |
+| pager_isearch_forward       | No     | Initiate an incremental search forward from current output point    |
+| pager_isearch_backward      | No     | Initiate an incremental search backward from current output point   |
+| pager_search_next           | No     | Move output to the next search match                                |
+| pager_search_prev           | No     | Move output to the prior search match                               |
+| search_toggle_regex         | No     | Toggle between regex and string search                              |
+| search_step_forward         | No     | Preview the next match using the current search text                |
+| search_step_backward        | No     | Preview the prior match using the current search text               |
+| isearch_next                | No     | Move output to the next isearch match                               |
+| isearch_prev                | No     | Move output to the prior isearch match                              |
+| search_accept               | No     | Commit the current search and close the search session              |
+| search_cancel               | No     | Cancel the active search session and restore its starting point     |
+| isearch_accept              | No     | Commit the current incremental search and close the search session  |
+| isearch_cancel              | No     | Cancel the active incremental search and restore its starting point |
+
+**** Popup actions
+Popup actions control selection and narrowing popups such as choose, menu,
+completion, and history popups. You can narrow the selections presented by
+typing in the input field presented.  You can move through the list, accept or
+cancel the selection, page through choices, jump to the top or bottom,
+recenter the selection, and toggle selection in multi-select popups.
+
+| Action Name           | Count? | Description                                               |
+|-----------------------+--------+-----------------------------------------------------------|
+| popup_cancel          | No     | Close the popup and return its cancel_value               |
+| popup_accept          | No     | Close the popup and return the selection                  |
+| popup_next            | No     | Move the selection cursor to the next item                |
+| popup_prev            | No     | Move the selection cursor to the prior item               |
+| popup_page_down       | No     | Move the selection list down one page                     |
+| popup_page_up         | No     | Move the selection list up one page                       |
+| popup_top             | No     | Move to the top of the selection list                     |
+| popup_bottom          | No     | Move to the bottom of the selection list                  |
+| popup_recenter        | No     | Recenter the selection list on the current item           |
+| popup_toggle_selected | No     | In multi-select, toggle the selection of the current item |
+
+**** Prompt popup actions
+Prompt popup actions control prompt dialogs that collect a string from the
+user. They accept the prompt, cancel it, or cancel only when the prompt is
+empty.
+
+| Action Name            | Count? | Description                                          |
+|------------------------+--------+------------------------------------------------------|
+| prompt_accept          | No     | Close the prompt popup and return the current string |
+| prompt_cancel          | No     | Close the prompt popup and return its cancel_value   |
+| prompt_cancel_if_empty | No     | Cancel only if the input buffer is empty             |
+
+**** Utility Actions
+Some actions exist to support =Fatty='s own input machinery and are not
+normally useful as ordinary user bindings. For example, =insert=, =replace=,
+and =paste= need text supplied by code: =paste= is used for bracketed paste
+events from the terminal and normalizes pasted text for a one-line input
+field; =self_insert= is selected automatically for printable characters.  They
+are listed here for completeness.
+
+| Action Name | Args | Count? | Description                        |
+|-------------+------+--------+------------------------------------|
+| insert      | str  | Yes    | Insert the string at point         |
+| self_insert |      | Yes    | Insert the bound key at point      |
+| replace     | str  | No     | Replace the buffer with the string |
+| set         | str  | No     | Alias for =replace=                |
+| paste       | str  | No     | Insert pasted text at point        |
+
+** Themes =themes/=
+*** Distributed Themes
+As distributed, =fatty= comes with the following themes, most of which are
+based on popular themes used in many text editors and IDEs.
+
+Within a =fatty= terminal, themes can be changed interactively.  The
+default Emacs-style bindings include:
+
+| Key     | Action                                  |
+|---------+-----------------------------------------|
+| ~C-M-t~ | cycle to the next loaded theme          |
+| ~M-=~   | preview and choose a theme from a popup |
+
+Here are the builtin themes:
+
+| Name             | Description                                        |
+|------------------+----------------------------------------------------|
+| capuchin_monk    | A tribute to St. Francis of Assisi                 |
+| catppuccin_latte | Pastel theme of the latte flavor                   |
+| catppuccin_mocha | Pastel theme of the mocha flavor                   |
+| cyberpunk        | Brash colorful theme                               |
+| dracula          | Dark theme inspired by the Count                   |
+| everforest_dark  | Dark green-esque theme                             |
+| gruvbox_dark     | Engineered for focus, built for developers         |
+| gruvbox_light    | Engineered for focus, built for developers         |
+| mono             | Minimal black-and-white theme                      |
+| monokai          | Based on https://monokai.pro/history               |
+| nordic           | Shiver me timbers, it's northern                   |
+| onedark          | Shameless imitation of Atom editor theme           |
+| solarized_dark   | Ethan Schoonover's famous terminal theme           |
+| solarized_light  | And its light variant                              |
+| terminal         | Use the terminal's color scheme                    |
+| tokyo_night      | Celebrates the neon lights and dark vibes of Tokyo |
+| wordperfect      | Nostalgic nod to the good old word processor       |
+
+*** Custom Themes
+**** Theme Name
+A Fatty theme is a YAML file in the user-specific config directory (normally
+=~/.config/fatty/themes=) or the app-specific config directory (by default
+=~/.config/fatty/apps/<app_name>/themes=).  The filename does not determine
+the theme name: the theme file must have a =name= field to set the name:
+
+#+begin_src yaml :tangle no
+name: nordic
+#+end_src
+
+**** Inheritance from Another Theme
+Themes can inherit from other themes with the =inherit:= tag:
+
+#+begin_src yaml :tangle no
+name: my_nordic
+inherit: nordic
+
+output:
+fg: "#eeeeee"
+#+end_src
+
+This means that all the theme setting from the =nordic= theme apply except to
+the extent changed by the rest of the =my_nordic= theme file.
+
+**** Inheritance within a Theme
+Not only may one theme inherit from another theme, some roles within a theme
+inherit from other roles.  For example, the =input= role inherits from the
+=output= role.
+
+Thus, a minimal theme can define only =output= and inherit everything else
+through Fatty's role defaults:
+
+#+begin_src yaml :tangle no
+name: simple_dark
+inherit: null
+
+output:
+  fg: white
+  bg: black
+#+end_src
+
+This means that the input field will have the same coloring and attributes as
+the output pane.
+
+**** Theme Roles
+Here is a listing of what roles act as the parent for each of the roles, their
+purpose, and the role, if any, from which they inherit.
+
+| Role name               | Used for                                  | Parent Role           |
+|-------------------------+-------------------------------------------+-----------------------|
+| =output=                | Main output area text.                    | <none>                |
+| =input=                 | Main command/input field.                 | =output=              |
+| =input_suggestion=      | Autosuggestion or completion suffix text. | =input=               |
+| =cursor=                | Cursor cell styling where applicable.     | =input=               |
+| =region=                | Selected text / active region.            | =output=              |
+| =status=                | Status area base role.                    | =output=              |
+| =info=                  | Informational messages.                   | =output=              |
+| =good=                  | Success messages.                         | =info=                |
+| =warn=                  | Warning messages.                         | =info=                |
+| =error=                 | Error messages.                           | =warn=                |
+| =alert=                 | Alert panel base role.                    | =output=              |
+| =pager_status=          | Pager status / prompt row.                | =status=              |
+| =line_number=           | Line numbers when toggled on              | =output=              |
+| =search_input=          | Search input field.                       | =popup=               |
+| =match_current=         | Current search match.                     | =region=              |
+| =match_other=           | Other search matches.                     | =region=              |
+| =popup=                 | Popup body.                               | =output=              |
+| =popup_frame=           | Popup border/frame.                       | =popup=               |
+| =popup_input=           | Popup filter/input field.                 | =input=               |
+| =popup_selection=       | Selected popup item row.                  | =region=              |
+| =popup_counts=          | Popup counts/status row.                  | =popup=               |
+| =markdown_h1=           | Markdown level-1 headings.                | =output=              |
+| =markdown_h2=           | Markdown level-2 headings.                | =markdown_h1=         |
+| =markdown_h3=           | Markdown level-3 headings.                | =markdown_h2=         |
+| =markdown_code=         | Inline markdown code.                     | =output=              |
+| =markdown_code_block=   | Markdown fenced-code block base role.     | =markdown_code=       |
+| =markdown_code_gutter=  | Code block gutter/prefix.                 | =markdown_code_block= |
+| =markdown_strong=       | Markdown strong/bold text.                | =output=              |
+| =markdown_emphasis=     | Markdown emphasized text.                 | =output=              |
+| =markdown_link=         | Markdown link text.                       | =output=              |
+| =markdown_url=          | Markdown displayed URL text.              | =markdown_link=       |
+| =markdown_quote_gutter= | Markdown block quote gutter.              | =output=              |
+| =markdown_highlight=    | Markdown highlight / marked text.         | =output=              |
+| =markdown_table_header= | Markdown table header cells.              | =markdown_strong=     |
+| =markdown_table_cell=   | Markdown table body cells.                | =output=              |
+| =markdown_underline=    | Markdown underline text.                  | =output=              |
+| =markdown_hrule=        | Markdown horizontal rules.                | =output=              |
+
+**** Role Colors and Attributes and Frame Style
+Each role can have assigned to it a foreground color (=fg:=), a background
+color (=bg:=), and one or more "attributes" (=attrs:=).
+
+***** Colors
+The colors can be a hex string of the form "#RRGGBB", that is a mixture of
+red, green, and blue at level given by three valid hexadecimal numbers RR, GG,
+and BB.  For example "#FF0000" is pure red, "#330044" is a middling mixture of
+red and blue, a shade of purple.  In addition, =fatty= recognizes color names
+defined as 16 ANSI colors, 256 xterm colors, and X11 colors, all of which you
+can see by invoking =fatty='s CLI command =colors=.
+
+The special color =default= means to inherit colors from the underlying terminal
+program.
+
+***** Attributes
+Each role can also have non-color attributes applied by specifying an =attrs=
+list.  Supported attributes are =bold=, =dim=, =italic=, =underline=, and
+=reverse=.  Italic is emitted by the truecolor renderer and by markdown ANSI
+output, but curses terminals may display it inconsistently or not at all.
+
+***** Frame Style
+In addition, one role, =popup_frame:=, in addition to these have two
+attributes for styling the "frame" drawn around popup:
+
+| =border:=  | single, double, or ascii |
+| =corners:= | rounded or square        |
+
+***** An Example Theme
+
+#+begin_src yaml :tangle no
+  name: example
+  inherit: null
+
+  output:
+    fg: "#d8dee9"
+    bg: "#2e3440"
+
+  input:
+    fg: "#eceff4"
+    bg: "#3b4252"
+    attrs: [bold]
+
+  input_suggestion:
+    fg: "#81a1c1"
+    bg: "#3b4252"
+
+  cursor:
+    fg: "#2e3440"
+    bg: "#88c0d0"
+
+  region:
+    fg: "#2e3440"
+    bg: "#88c0d0"
+
+  info:
+    fg: "#d8dee9"
+    bg: "#2e3440"
+
+  good:
+    fg: green
+    bg: "#2e3440"
+
+  warn:
+    fg: "#2e3440"
+    bg: "#ebcb8b"
+
+  error:
+    fg: "#eceff4"
+    bg: "#bf616a"
+
+  pager_status:
+    fg: black
+    bg: lightgreen
+
+  search_input:
+    fg: black
+    bg: cyan
+
+  match_current:
+    fg: black
+    bg: yellow
+
+  match_other:
+    fg: black
+    bg: lightgray
+
+  popup:
+    fg: "#d8dee9"
+    bg: "#3b4252"
+
+  popup_input:
+    fg: "#eceff4"
+    bg: "#434c5e"
+
+  popup_selection:
+    fg: "#2e3440"
+    bg: "#88c0d0"
+
+  popup_counts:
+    fg: "#2e3440"
+    bg: white
+
+  popup_frame:
+    fg: "#81a1c1"
+    bg: "#3b4252"
+    border: single
+    corners: rounded
+#+end_src
+
+
+Or you can group them under =markdown= without the =markdown_= prefix:
+
+#+begin_src yaml :tangle no
+  markdown:
+    h1:
+      fg: yellow
+      bg: navy
+      attrs: [bold]
+    code:
+      fg: lightgreen
+      bg: black
+    link:
+      fg: cyan
+      bg: navy
+      attrs: [underline]
+#+end_src