[session] some more session docs

docs/source/usage.rst

@@ -1,4 +1,3 @@
-
 .. _usage:
 
 Usage
@@ -263,3 +262,30 @@ commands into a :ref:`script<scripts>` and execute that script with the
 
 .. [#] The expression :code:`regexp_match('bound to ([^ ]+)', log_body) as ip`
    can be used to extract the IP address from the log message body.
+
+Sharing Sessions With Others
+----------------------------
+
+After setting up filters, bookmarks, and making notes, you might want to share
+your work with others.  If they have access to the same log files, you can
+use the :ref:`:export-session-to<export_session_to>` command to write an
+executable **lnav** script that will recreate the current session state.  The
+script contains various SQL statements and **lnav** commands that capture the
+current state.  So, you should feel free to modify the script or use it as a
+reference to learn about more advanced uses of lnav.
+
+The script will capture the file paths that were explicitly specified and
+not the files that were actually opened.  For example, if you specified
+"/var/log" on the command line, the script will include
+:code:`:open /var/log/*` and not an individual open for each file in that
+directory.
+
+Also, in order to support archives of log files, lnav will try to find the
+directory where the archive was unpacked and use that as the base for the
+:code:`:open` command.  Currently, this is done by searching for the top
+"README" file in the directory hierarchy containing the files [1]_.  The
+consumer of the session script can then set the :code:`LOG_DIR_0` (or 1, 2,
+...) environment variable to change where the log files will be loaded from.
+
+.. [1] It is assumed a log archive would have a descriptive README file.
+   Other heuristics may be added in the future.

src/internals/cmd-ref.rst

@@ -483,7 +483,7 @@
 :export-session-to *path*
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-  Export the current lnav state to an lnav script file
+  Export the current lnav state to an executable lnav script file that contains the commands needed to restore the current session
 
   **Parameters**
     * **path\*** --- The path to the file to write

src/lnav_commands.cc

@@ -5473,7 +5473,9 @@ readline_context::command_t STD_COMMANDS[] = {
      com_export_session_to,
 
      help_text(":export-session-to")
-         .with_summary("Export the current lnav state to an lnav script file")
+         .with_summary("Export the current lnav state to an executable lnav "
+                       "script file that contains the commands needed to "
+                       "restore the current session")
          .with_parameter(help_text("path", "The path to the file to write"))
          .with_tags({"io", "scripting"})},
     {"rebuild",

src/session.export.cc

@@ -207,6 +207,7 @@ SELECT content_id, format, time_offset FROM lnav_file
 )";
 
     static constexpr const char LOG_DIR_INSERT[] = R"(
+# Set this environment variable to override this value or edit this script.
 ;INSERT OR IGNORE INTO environ (name, value) VALUES ('LOG_DIR_{}', {})
 )";
 
@@ -447,6 +448,12 @@ SELECT content_id, format, time_offset FROM lnav_file
                     continue;
                 }
 
+                if (ld->get_file_ptr()->get_open_options().loo_source
+                    == logfile_name_source::ARCHIVE)
+                {
+                    continue;
+                }
+
                 auto container_path_opt
                     = find_container_dir(ld->get_file_ptr()->get_path());
                 if (!container_path_opt) {

test/expected/test_cmds.sh_b6a3bb78e9d60e5e1f5ce5b18e40d2f1662707ab.out

@@ -982,7 +982,8 @@ For support questions, email:
 
 :export-session-to path
 ══════════════════════════════════════════════════════════════════════
-  Export the current lnav state to an lnav script file
+  Export the current lnav state to an executable lnav script file that
+  contains the commands needed to restore the current session
 Parameter
   path   The path to the file to write
 See Also

test/expected/test_sessions.sh_6d87ff483d5785c58fb271a405ff1c35e4f83cd9.out

@@ -9,6 +9,7 @@
 # The files loaded into the session were:
 
 
+# Set this environment variable to override this value or edit this script.
 ;INSERT OR IGNORE INTO environ (name, value) VALUES ('LOG_DIR_0', '{test_dir}')
 :open $LOG_DIR_0/support-dump/logfile_access_log.0
 :open $LOG_DIR_0/support-dump/logfile_access_log.1