1 files changed, 280 insertions, 0 deletions
diff --git a/docs/source/ui.rst b/docs/source/ui.rst
new file mode 100644
index 0000000..c7d7ffe
--- /dev/null
+++ b/docs/source/ui.rst
@@ -0,0 +1,280 @@
+.. _ui:
+
+User Interface
+==============
+
+The **lnav** TUI displays the content of the current "view" in the middle,
+with status bars above and below, and the interactive prompt as the last line.
+
+.. figure:: lnav-ui.png
+   :align: center
+   :alt: Screenshot of lnav showing a mix of syslog and web access_log messages.
+
+   Screenshot of **lnav** viewing syslog and web access_log messages.
+
+The default view shows the log messages from the log files that have been
+loaded.  There are other views for displaying content like plaintext files
+and SQL results.  The :ref:`ui_views` section describes the characteristics of
+each view in more detail.  You can switch to the different views using the
+hotkeys described in the :ref:`hotkeys_display` section or by pressing
+:kbd:`ENTER` to activate the breadcrumb bar, moving to the first crumb, and
+then selecting the desired view.  You can switch back to the previous view by
+pressing :kbd:`q`.  You can switch forward to the new view by pressing
+:kbd:`a`.  If the views are time-based (e.g. log and histogram), pressing
+:kbd:`Shift` + :kbd:`q` and :kbd:`Shift` + :kbd:`a` will synchronize the top
+times in the views.
+
+The right side of the display has a proportionally sized 'scrollbar' that
+shows:
+
+* the current position in the file;
+* the locations of errors/warnings in the log files by using red or yellow
+  coloring;
+* the locations of search hits by using a tick-mark pointing to the left;
+* the locations of bookmarks by using a tick-mark pointing to the right.
+
+Top Status Bar
+--------------
+
+The top status bar shows the current time and messages stored in the
+:ref:`table_lnav_user_notifications` table.
+
+Below the top status bar is the breadcrumb bar that displays the semantic
+location of the top line in the main view.  For example, within a
+pretty-printed JSON document, it will show the path to property at the top
+of the view.  The actual content of the bar depends on the current view and
+will be updated as you navigate around the main view.  The bar can also be
+used to navigate around the document by focusing on it.
+
+Breadcrumb Bar
+--------------
+
+.. figure:: lnav-breadcrumbs-help.png
+   :align: center
+   :figwidth: 90%
+
+   Screenshot of the breadcrumb bar focused and navigating the help text
+
+To focus on the breadcrumb bar, press :kbd:`ENTER`.  The :kbd:`←`/:kbd:`→`
+cursor keys can be used to select a crumb and the :kbd:`↑`/:kbd:`↓` keys can
+be used select a value of that crumb.  To accept a value and drop focus on the
+bar, press :kbd:`ENTER`.  To accept a value and move to the next crumb, press
+:kbd:`→`.  Using :kbd:`→` makes it quicker to drill down into a document
+without having to constantly switch focus.  To drop focus on the bar without
+accepting anything, press :kbd:`Escape`.
+
+There are three types of crumbs:
+
+* a dropdown where one of a limited set of values can be selected;
+* a combobox where a value can be entered directly or selected;
+* a numeric input for entering array indexes.
+
+When a dropdown or combobox is selected, you can type part of the desired value
+to filter the list of values.  For example, the first crumb is always the
+current view, typing in "hi" will filter the list down to the "HIST" value.
+
+Configuration Panels
+--------------------
+
+.. figure:: lnav-config-header.png
+   :align: center
+   :figwidth: 90%
+
+   Screenshot of the header for the configuration panels when they are hidden.
+
+After the main view content, there is a header bar for two configuration
+panels: Files and Filters.  These panels provide visual access to parts of
+lnav's configuration.  To access the panels, press the :kbd:`TAB` key.
+To hide the panels again, press :kbd:`q`.
+
+.. figure:: lnav-files-panel.png
+   :align: center
+   :figwidth: 90%
+
+   Screenshot of the files panel showing the loaded files.
+
+The Files panel is open initially to display progress in loading files.
+The following information can be displayed for each file:
+
+* the "unique" portion of the path relative to the other files;
+* the amount of data that has been indexed;
+* the date range of log messages contained in the file;
+* the errors that were encountered while trying to index the file;
+* the notes recorded for files where some automatic action was taken,
+  like hiding the file if it was seen as a duplicate of another file.
+
+.. figure:: lnav-filters-panel.png
+   :align: center
+   :figwidth: 90%
+
+   Screenshot of the filters panel showing an OUT and a disabled IN filter.
+
+If the view supports filtering, there will be a status line showing the
+following:
+
+* the number of enabled filters and the total number of filters;
+* the number of lines that are **not** displayed because of filtering.
+
+To edit the filters, you can press TAB to change the focus from the main
+view to the filter editor.  The editor allows you to create, enable/disable,
+and delete filters easily.
+
+Bottom Status Bar
+-----------------
+
+The second to last line is the bottom status bar, which shows the following:
+
+* the line number of the top line, starting from zero;
+* the location within the view, as a percentage;
+* the current search hit, the total number of hits, and the search term;
+* the loading indicator.
+
+When the interactive prompt is active, this bar can show the prompt
+description, help text, or error message.
+
+Prompt
+------
+
+Finally, the last line on the display is where you can enter search
+patterns and execute internal commands, such as converting a
+unix-timestamp into a human-readable date.  The following key-presses
+will activate a corresponding prompt:
+
+* :kbd:`/` - The search prompt.  You can enter a PCRE2-flavored regular
+  expression to search for in the current view.
+* :kbd:`:` - The command prompt.  Commands are used to perform common
+  operations.
+* :kbd:`;` - The SQL prompt.  SQL queries can be used for log analysis
+  and manipulating **lnav**'s state.
+* :kbd:`|` - The script prompt.  Enter a path to the lnav script to
+  execute, along with the arguments to pass in.
+
+The command-line is by the readline library, so the usual set of keyboard
+shortcuts can be used for editing and moving within the command-line.
+
+.. _ui_views:
+
+Views
+-----
+
+The accessible content within lnav is separated into the following views.
+
+LOG
+^^^
+
+The log view displays the log messages from any loaded log files in time
+order.  This view will be shown by default if any log messages are available.
+
+On color displays, the log messages will be highlighted as follows:
+
+* Errors will be colored in red;
+* warnings will be yellow;
+* search hits are reverse video;
+* various color highlights will be applied to: IP addresses, SQL keywords,
+  XML tags, file and line numbers in Java backtraces, and quoted strings;
+* "identifiers" in the messages will be randomly assigned colors based on their
+  content (works best on "xterm-256color" terminals).
+
+.. note::
+
+  If the coloring is too much for your tastes, you can change to the
+  "grayscale" theme by entering the following command:
+
+  .. code-block::  lnav
+
+    :config /ui/theme grayscale
+
+.. note::
+
+  If a log message has a timestamp that is out-of-order with its neighboring
+  messages, the timestamp will be highlighted in yellow.  When one of these
+  messages is at the top of the log view, an overlay will display the
+  difference between the "actual time" and the "received time".  The "actual
+  time" is the original textual timestamp.  The "received time" is the time
+  of an earlier message that is larger than this log message's time.
+
+The breadcrumb bar will show the following crumbs:
+
+* the timestamp for the top line;
+* the log format for the top line;
+* the name of the file the top line was pulled from;
+* the "operation ID" of the top log message, if it is supported by the log
+  format.
+
+These crumbs are interactive and can be used to navigate to different parts
+of the log view.  For example, selecting a different value in the log format
+crumb will jump to the first message with that format.
+
+TEXT
+^^^^
+
+The text view displays files for which lnav could not detect any log messages.
+
+Markdown
+""""""""
+
+Files with an :code:`.md` (or :code:`.markdown`) extension will be treated as
+Markdown files and rendered separately.
+
+DB
+^^
+
+The DB view shows the results of queries done through the SQLite interface.
+You can execute a query by pressing :kbd:`;` and then entering a SQL statement.
+You can switch to the SQL view by pressing :kbd:`v`.
+
+HELP
+^^^^
+
+The help view displays the builtin help text.  Press :kbd:`?` to switch to the
+help view at any time.  While in the help view, the breadcrumb bar can be used
+to navigate to different sections of the document.
+
+HIST
+^^^^
+
+The histogram view displays a stacked bar chart of messages over time
+classified by their log level and whether they've been bookmarked.  Press
+:kbd:`i` to switch back and forth to the histogram view.  You can also press
+:kbd:`Shift`+:kbd:`i` to toggle the histogram view while synchronizing the top
+time.  While in the histogram view, pressing :kbd:`z`/:kbd:`Shift`+:kbd:`z`
+will zoom in/out.
+
+PRETTY
+^^^^^^
+
+The pretty-print view takes the text displayed in the current view and shows
+the result of a pretty-printer run on that text.  For example, if a log
+message contained an XML message on a single line, the pretty-printer would
+break the XML across multiple lines with appropriate indentation.
+
+SCHEMA
+^^^^^^
+
+The schema view displays the current schema of the builtin SQLite database.
+
+SPECTRO
+^^^^^^^
+
+The spectrogram view is a "three"-dimensional display of data points of a log
+field or a SQL query column.  The dimensions are time on the Y axis, the range
+of data point values on the X axis, and the number of data points as a color.
+For example, if you were to visualize process CPU usage over time, the range
+of values on the X axis would be CPU percentages and there would be colored
+blocks at each point on the line where a process had that CPU percentage, like
+so
+
+.. figure:: lnav-spectro-cpu-pct.png
+   :align: center
+
+   Screenshot of the **lnav** spectrogram view showing CPU usage of processes.
+
+The colors correspond to the relative number of data points in a bucket.
+The legend overlaid at the top line in the view shows the counts of data
+points that are in a particular color, with green having the fewest number of
+data points, yellow the middle, and red the most.  You can select a particular
+bucket using the cursor keys to see the exact number of data points and the
+range of values.  The panel at the bottom of the view shows the data points
+themselves from the original source, the log file or the SQL query results.
+You can press :kbd:`TAB` to focus on the details panel so you can scroll
+around and get a closer look at the values.