[docs] some more README.md files

README.md

@@ -13,36 +13,36 @@ no setup.
 
 ### Links
 
-* [Main Site](https://lnav.org)
-* [**Documentation**](https://lnav.readthedocs.io) on Read the Docs
+- [Main Site](https://lnav.org)
+- [**Documentation**](https://lnav.readthedocs.io) on Read the Docs
 
 ## Contributing
 
-* [Become a Sponsor on GitHub](https://github.com/sponsors/tstack)
-* [Make a one-time donation on Ko-fi](https://ko-fi.com/tstack)
+- [Become a Sponsor on GitHub](https://github.com/sponsors/tstack)
+- [Make a one-time donation on Ko-fi](https://ko-fi.com/tstack)
 
 ## Features
 
-* Log messages from different files are collated together into a single view
-* Automatic detection of log format
-* Automatic decompression of GZip and BZip2 files
-* Filter log messages based on regular expressions
-* Use SQL to analyze your logs
-* And more...
+- Log messages from different files are collated together into a single view
+- Automatic detection of log format
+- Automatic decompression of GZip and BZip2 files
+- Filter log messages based on regular expressions
+- Use SQL to analyze your logs
+- And more...
 
 ## Prerequisites
 
 The following software packages are required to build lnav:
 
-* gcc/clang  - A C++14-compatible compiler.
-* libpcre    - The Perl Compatible Regular Expression (PCRE) library.
-* sqlite     - The SQLite database engine.  Version 3.9.0 or higher is required.
-* ncurses    - The ncurses text UI library.
-* readline   - The readline line editing library.
-* zlib       - The zlib compression library.
-* bz2        - The bzip2 compression library.
-* libcurl    - The cURL library for downloading files from URLs.  Version 7.23.0 or higher is required.
-* libarchive - The libarchive library for opening archive files, like zip/tgz.
+- gcc/clang  - A C++14-compatible compiler.
+- libpcre    - The Perl Compatible Regular Expression (PCRE) library.
+- sqlite     - The SQLite database engine.  Version 3.9.0 or higher is required.
+- ncurses    - The ncurses text UI library.
+- readline   - The readline line editing library.
+- zlib       - The zlib compression library.
+- bz2        - The bzip2 compression library.
+- libcurl    - The cURL library for downloading files from URLs.  Version 7.23.0 or higher is required.
+- libarchive - The libarchive library for opening archive files, like zip/tgz.
 
 ## Installation
 
@@ -50,10 +50,11 @@ Lnav follows the usual GNU style for configuring and installing software:
 
 Run `./autogen.sh` if compiling from a cloned repository.
 
-    $ ./configure
-    $ make
-    $ sudo make install
-
+```
+$ ./configure
+$ make
+$ sudo make install
+```
 
 ## Cygwin users
 
@@ -63,7 +64,9 @@ Alternatively, you can get the generated binary from [AppVeyor](https://ci.appve
 
 Remember that you still need the lnav dependencies under Cygwin, here is a quick way to do it:
 
-    setup-x86_64.exe -q -P libpcre1 -P libsqlite3_0 -P libstdc++6
+```
+setup-x86_64.exe -q -P libpcre1 -P libsqlite3_0 -P libstdc++6
+```
 
 Currently, the x64 version seems to be working better than the x86 one.
 
@@ -72,44 +75,60 @@ Currently, the x64 version seems to be working better than the x86 one.
 The only file installed is the executable, `lnav`.  You can execute it
 with no arguments to view the default set of files:
 
-    $ lnav
+```
+$ lnav
+```
 
 You can view all the syslog messages by running:
 
-    $ lnav /var/log/messages*
+```
+$ lnav /var/log/messages*
+```
 
 ### Usage with `systemd-journald`
 
 On systems running `systemd-journald`, you can use `lnav` as the pager:
 
-    $ journalctl | lnav
+```
+$ journalctl | lnav
+```
 
 or in follow mode:
 
-    $ journalctl -f | lnav
+```
+$ journalctl -f | lnav
+```
 
 Since `journalctl`'s default output format omits the year, if you are
 viewing logs which span multiple years you will need to change the
 output format to include the year, otherwise `lnav` gets confused:
 
-    $ journalctl -o short-iso | lnav
+```
+$ journalctl -o short-iso | lnav
+```
 
 It is also possible to use `journalctl`'s json output format and `lnav`
-will make use of additional fields such as PRIORITY and _SYSTEMD_UNIT:
+will make use of additional fields such as PRIORITY and \_SYSTEMD_UNIT:
 
-    $ journalctl -o json | lnav
+```
+$ journalctl -o json | lnav
+```
 
 In case some MESSAGE fields contain special characters such as
 ANSI color codes which are considered as unprintable by journalctl,
 specifying `journalctl`'s `-a` option might be preferable in order
 to output those messages still in a non binary representation:
 
-    $ journalctl -a -o json | lnav
+```
+$ journalctl -a -o json | lnav
+```
 
 If using systemd v236 or newer, the output fields can be limited to
 the ones actually recognized by `lnav` for increased efficiency:
 
-    $ journalctl -o json --output-fields=MESSAGE,PRIORITY,_PID,SYSLOG_IDENTIFIER,_SYSTEMD_UNIT | lnav
+```
+$ journalctl -o json --output-fields=MESSAGE,PRIORITY,_PID,SYSLOG_IDENTIFIER,_SYSTEMD_UNIT | lnav
+```
 
 If your system has been running for a long time, for increased
 efficiency you may want to limit the number of log lines fed into

src/base/README.md

@@ -1,3 +1 @@
-
 # libbase -- Library of utility functions
-

src/base/date_time_scanner.hh

@@ -84,7 +84,7 @@ struct date_time_scanner {
 
             localtime_r(&t, &tm_out.et_tm);
 #ifdef HAVE_STRUCT_TM_TM_ZONE
-            tm_out.et_tm.tm_zone = NULL;
+            tm_out.et_tm.tm_zone = nullptr;
 #endif
             tm_out.et_tm.tm_isdst = 0;
 
@@ -131,7 +131,7 @@ struct date_time_scanner {
         if (time_len == -1) {
             time_len = strlen(time_src);
         }
-        if (this->scan(time_src, time_len, time_fmt, &tm, tv_out) != NULL) {
+        if (this->scan(time_src, time_len, time_fmt, &tm, tv_out) != nullptr) {
             return true;
         }
         return false;
@@ -142,7 +142,7 @@ struct date_time_scanner {
         struct exttm tm;
 
         if (this->scan(time_src.c_str(), time_src.size(),
-                       NULL, &tm, tv_out) != NULL) {
+                       nullptr, &tm, tv_out) != nullptr) {
             return true;
         }
         return false;

src/base/enum_util.hh

@@ -32,10 +32,16 @@
 
 #include <type_traits>
 
+namespace lnav {
+namespace enums {
+
 template <typename E>
 constexpr auto to_underlying(E e) noexcept
 {
     return static_cast<std::underlying_type_t<E>>(e);
 }
 
+}
+}
+
 #endif

src/base/lnav_log.cc

@@ -309,7 +309,7 @@ void log_msg(lnav_log_level_t level, const char *src_file, int line_number,
         localtm.tm_min,
         localtm.tm_sec,
         (int)(curr_time.tv_usec / 1000),
-        LEVEL_NAMES[to_underlying(level)],
+        LEVEL_NAMES[lnav::enums::to_underlying(level)],
         current_thid.t_id,
         src_file,
         line_number);

src/filter_sub_source.cc

@@ -44,11 +44,11 @@ filter_sub_source::filter_sub_source()
 {
     this->fss_regex_context.set_highlighter(readline_regex_highlighter)
         .set_append_character(0);
-    this->fss_editor.add_context(to_underlying(filter_lang_t::REGEX),
+    this->fss_editor.add_context(lnav::enums::to_underlying(filter_lang_t::REGEX),
                                  this->fss_regex_context);
     this->fss_sql_context.set_highlighter(readline_sqlite_highlighter)
         .set_append_character(0);
-    this->fss_editor.add_context(to_underlying(filter_lang_t::SQL),
+    this->fss_editor.add_context(lnav::enums::to_underlying(filter_lang_t::SQL),
                                  this->fss_sql_context);
     this->fss_editor.set_change_action(bind_mem(
         &filter_sub_source::rl_change, this));
@@ -161,7 +161,7 @@ bool filter_sub_source::list_input_handle_key(listview_curses &lv, int ch)
             this->fss_editing = true;
 
             add_view_text_possibilities(&this->fss_editor,
-                                        to_underlying(filter_lang_t::REGEX),
+                                        lnav::enums::to_underlying(filter_lang_t::REGEX),
                                         "*",
                                         top_view);
             this->fss_editor.set_window(lv.get_window());
@@ -170,7 +170,7 @@ bool filter_sub_source::list_input_handle_key(listview_curses &lv, int ch)
                 lv.get_y() + (int) (lv.get_selection() - lv.get_top()));
             this->fss_editor.set_left(25);
             this->fss_editor.set_width(this->tss_view->get_width() - 8 - 1);
-            this->fss_editor.focus(to_underlying(filter_lang_t::REGEX), "", "");
+            this->fss_editor.focus(lnav::enums::to_underlying(filter_lang_t::REGEX), "", "");
             this->fss_filter_state = true;
             ef->disable();
             return true;
@@ -196,7 +196,7 @@ bool filter_sub_source::list_input_handle_key(listview_curses &lv, int ch)
             this->fss_editing = true;
 
             add_view_text_possibilities(&this->fss_editor,
-                                        to_underlying(filter_lang_t::REGEX),
+                                        lnav::enums::to_underlying(filter_lang_t::REGEX),
                                         "*",
                                         top_view);
             this->fss_editor.set_window(lv.get_window());
@@ -205,7 +205,7 @@ bool filter_sub_source::list_input_handle_key(listview_curses &lv, int ch)
                 lv.get_y() + (int) (lv.get_selection() - lv.get_top()));
             this->fss_editor.set_left(25);
             this->fss_editor.set_width(this->tss_view->get_width() - 8 - 1);
-            this->fss_editor.focus(to_underlying(filter_lang_t::REGEX), "", "");
+            this->fss_editor.focus(lnav::enums::to_underlying(filter_lang_t::REGEX), "", "");
             this->fss_filter_state = true;
             ef->disable();
             return true;
@@ -225,11 +225,11 @@ bool filter_sub_source::list_input_handle_key(listview_curses &lv, int ch)
             this->fss_editing = true;
 
             add_view_text_possibilities(&this->fss_editor,
-                                        to_underlying(filter_lang_t::REGEX),
+                                        lnav::enums::to_underlying(filter_lang_t::REGEX),
                                         "*",
                                         top_view);
             add_filter_expr_possibilities(&this->fss_editor,
-                                          to_underlying(filter_lang_t::SQL),
+                                          lnav::enums::to_underlying(filter_lang_t::SQL),
                                           "*");
             this->fss_editor.set_window(lv.get_window());
             this->fss_editor.set_visible(true);
@@ -237,7 +237,7 @@ bool filter_sub_source::list_input_handle_key(listview_curses &lv, int ch)
                 lv.get_y() + (int) (lv.get_selection() - lv.get_top()));
             this->fss_editor.set_left(25);
             this->fss_editor.set_width(this->tss_view->get_width() - 8 - 1);
-            this->fss_editor.focus(to_underlying(tf->get_lang()), "");
+            this->fss_editor.focus(lnav::enums::to_underlying(tf->get_lang()), "");
             this->fss_editor.rewrite_line(0, tf->get_id().c_str());
             this->fss_filter_state = tf->is_enabled();
             tf->disable();

src/formats/README.md

@@ -0,0 +1,4 @@
+# Formats
+
+This directory contains the built-in log file format definitions.  These files
+are converted to C by `bin2c` and compiled into the executable.

src/internals/README.md

@@ -0,0 +1,4 @@
+# Internals
+
+This directory contains documentation fragments that are generated from lnav's
+built-in help and schemas.

src/internals/config-v1.schema.json

@@ -19,13 +19,13 @@
                     "properties": {
                         "min-free-space": {
                             "title": "/tuning/archive-manager/min-free-space",
-                            "description": "The minimum free space to maintain when unpacking",
+                            "description": "The minimum free space, in bytes, to maintain when unpacking archives",
                             "type": "integer",
                             "minimum": 0
                         },
                         "cache-ttl": {
                             "title": "/tuning/archive-manager/cache-ttl",
-                            "description": "The time-to-live for unpacked archives",
+                            "description": "The time-to-live for unpacked archives, expressed as a duration (e.g. '3d' for three days)",
                             "type": "string"
                         }
                     },

src/keymaps/README.md

@@ -0,0 +1,4 @@
+# Keymaps
+
+This directory contains the built-in keymap definitions.  The files are
+turned into C using `bin2c` and compiled into the executable.

src/lnav_config.cc

@@ -867,12 +867,16 @@ static struct json_path_container ui_handlers = {
 
 static struct json_path_container archive_handlers = {
     yajlpp::property_handler("min-free-space")
-        .with_description("The minimum free space to maintain when unpacking")
+        .with_description(
+            "The minimum free space, in bytes, to maintain when unpacking "
+            "archives")
         .with_min_value(0)
         .for_field(&_lnav_config::lc_archive_manager,
                    &archive_manager::config::amc_min_free_space),
     yajlpp::property_handler("cache-ttl")
-        .with_description("The time-to-live for unpacked archives")
+        .with_description(
+            "The time-to-live for unpacked archives, expressed as a duration "
+            "(e.g. '3d' for three days)")
         .for_field(&_lnav_config::lc_archive_manager,
                    &archive_manager::config::amc_cache_ttl),
 };

src/scripts/README.md

@@ -0,0 +1,4 @@
+# Scripts
+
+This directory contains the built-in lnav scripts.  The files are
+turned into C using `bin2c` and compiled into the executable.

src/themes/README.md

@@ -1,4 +1,3 @@
-
 # Themes
 
 This directory contains the built-in theme definitions.  The files are

src/yajlpp/README.md

@@ -0,0 +1,5 @@
+# YAJLPP
+
+This directory contains a C++ adapter for the YAJL JSON library.  The adapter
+provides a usage model that is based around client code mapping internal data
+structures to a JSON schema.