Merging upstream version 0.12.2.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 97 insertions, 4 deletions

diff --git a/docs/source/usage.rst b/docs/source/usage.rst
index d43ed52..df50c7d 100644
--- a/docs/source/usage.rst
+++ b/docs/source/usage.rst
@@ -116,6 +116,68 @@ file.
   The binary file is named ``tailer.bin.XXXXXX`` where *XXXXXX* is 6 random digits.
   The file is, under normal circumstancies, deleted immediately.
 
+Command Output
+^^^^^^^^^^^^^^
+
+The output of commands can be captured and displayed in **lnav** using
+the :ref:`:sh<sh>` command or by passing the :option:`-e` option on the
+command-line.   The captured output will be displayed in the TEXT view.
+The lines from stdout and stderr are recorded separately so that the
+lines from stderr can be shown in the theme's "error" highlight.  The
+time that the lines were received are also recorded internally so that
+the "time-offset" display (enabled by pressing :kbd:`Shift` + :kbd:`T`)
+can be shown and the "jump to slow-down" hotkeys (:kbd:`s` /
+:kbd:`Shift` + :kbd:`S`) work.  Since the line-by-line timestamps are
+recorded internally, they will not interfere with timestamps that are
+in the commands output.
+
+Docker Logs
+^^^^^^^^^^^
+
+To make it easier to view
+`docker logs <https://docs.docker.com/engine/reference/commandline/logs/>`_
+within **lnav**, a :code:`docker://` URL scheme is available.  Passing
+the container name in the authority field will run the :code:`docker logs`
+command.  If a path is added to the URL, then **lnav** will execute
+:code:`docker exec <container> tail -F -n +0 /path/to/file` to try and
+tail the file in the container.
+
+Custom URL Schemes
+^^^^^^^^^^^^^^^^^^
+
+Custom URL schemes can be defined using the :ref:`/tuning/url-schemes<url_scheme>`
+configuration.  By adding a scheme name to the tuning configuration along
+with the name of an **lnav** handler script, you can control how the URL is
+interpreted and turned into **lnav** commands.  This feature is how the
+`Docker Logs`_ functionality is implemented.
+
+Custom URLs can be passed on the command-line or to the :ref:`:open<open>`
+command.  When passed on the command-line, an :code:`:open` command with the
+URL is added to the list of initial commands.  When the :code:`:open` command
+detects a custom URL, it checks for the definition in the configuration.
+If found, it will call the associated handler script with the URL as the
+first parameter.  The script can parse the URL using the :ref:`parse_url`
+SQL function, if needed.  The script should then execute whatever commands
+it needs to open the destination for viewing in **lnav**.  For example,
+the docker URL handler uses the :ref:`:sh<sh>` command to run
+:code:`docker logs` with the container.
+
+Using as a PAGER
+^^^^^^^^^^^^^^^^
+
+Setting **lnav** as your :envvar:`PAGER` can have some advantages, like
+basic syntax highlighting and discovering sections in a document.  For
+example, when viewing a man page, the current section is displayed in
+the breadcrumb bar and you can jump to a section with the
+:ref:`:goto<goto>` command.
+
+You will probably want to pass the :option:`-q` option to suppress the
+message showing the path to the captured input.
+
+.. prompt:: bash
+
+   export PAGER="lnav -q"
+
 Searching
 ---------
 
@@ -203,10 +265,41 @@ columns will be included in the table.
 Taking Notes
 ------------
 
-A few of the columns in the log tables can be updated on a row-by-row basis to
-allow you to take notes.  The majority of the columns in a log table are
-read-only since they are backed by the log files themselves.  However, the
-following columns can be changed by an :code:`UPDATE` statement:
+As you are looking through logs, you might find that you want to leave some
+notes of your findings.  **lnav** can help here by saving information in
+the session without needing to modify the actual log files.  Thus, when
+you re-open the files in lnav, the notes will be restored.  The following
+types of information can be saved:
+
+:tags: Log messages can be tagged with the :ref:`:tag<tag>` command as a
+  simple way to leave a descriptive mark.  The tags attached to a
+  message will be shown underneath the message.  You can press
+  :kbd:`u` and :kbd:`Shift` + :kbd:`u` to jump to the next/previous
+  marked line.  A regular search will also match tags.
+
+:comments: Free-form text can be attached to a log message with the
+  :ref:`:comment<comment>` command.  The comment will be shown
+  underneath the message. If the text contains markdown syntax,
+  it will be rendered to the best of the terminal's ability.
+  You can press :kbd:`u` and :kbd:`Shift` + :kbd:`u` to jump to the
+  next/previous marked line.  A regular search will also match the
+  comment text.
+
+:partitions: The log view can be partitioned to provide some context
+  about where you are in a collection of logs.  For example, in logs
+  for a test run, partitions could be created with the name for each
+  test.  The current partition is shown in the breadcrumb bar and
+  prefixed by the "⊑" symbol.  You can select the partition breadcrumb
+  to jump to another partition.  Pressing :kbd:`{` and :kbd:`}` will
+  jump to the next/previous partition.
+
+Accessing notes through the SQLite interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The note taking functionality in lnav can also be accessed through the
+log tables exposed through SQLite.  The majority of the columns in a log
+table are read-only since they are backed by the log files themselves.
+However, the following columns can be changed by an :code:`UPDATE` statement:
 
 * **log_part** - The "partition" the log message belongs to.  This column can
   also be changed by the :ref:`:partition-name<partition_name>` command.