[dbtool] Move examples behind --show-examples

The Examples block bloated the bottom of `dbtool --help`, pushing the
options listing off the screen. Hoist it behind a dedicated
`--show-examples` flag and leave a one-line pointer at the end of help
output so discoverability is preserved without forcing the whole
example wall on every `--help` reader.

Signed-off-by: Christian Parpart <christian@parpart.family>

Author: christianparpart

src/tools/dbtool/main.cpp

@@ -197,10 +197,20 @@ void PrintUsage()
     std::println("  {}--schema-only{}             Backup/restore schema only, skip data",
                  c.option, c.reset);
     std::println("  {}--quiet{}                   Suppress progress output", c.option, c.reset);
+    std::println("  {}--show-examples{}           Show usage examples and exit", c.option, c.reset);
     std::println("  {}--help{}                    Show this help message", c.option, c.reset);
     std::println("");
+    std::println("Run {}dbtool --show-examples{} to see usage examples.", c.option, c.reset);
+    // clang-format on
+}
+
+void PrintExamples()
+{
+    // clang-format off
+    auto const c = IsStdoutTerminal() ? HelpColors::Colored() : HelpColors::Plain();
 
     std::println("{}Examples:{}", c.heading, c.reset);
+    std::println("");
 
     std::println("  {}# Apply pending migrations using an SQLite database file via ODBC:{}", c.example, c.reset);
     std::println("  {}dbtool migrate --connection-string \"DRIVER=SQLite3;Database=test.db\"{}", c.code, c.reset);
@@ -409,6 +419,11 @@ std::expected<Options, std::string> ParseArguments(int argc, char** argv)
             options.command = "help";
             break;
         }
+        else if (arg == "--show-examples")
+        {
+            options.command = "show-examples";
+            break;
+        }
         else if (arg == "--plugins-dir")
         {
             if (i + 1 >= argc)
@@ -2239,6 +2254,12 @@ int main(int argc, char** argv)
             return EXIT_SUCCESS;
         }
 
+        if (options.command == "show-examples")
+        {
+            PrintExamples();
+            return EXIT_SUCCESS;
+        }
+
         if (options.command == "resolve-secret")
             return ResolveSecretCommand(options);