revamp all tools help messages

The general idea is: A small paragraph on the tool itself as a
description, a list of the most used (!= all) commands available in the
tool, a remark where to find more information on the tool and its
commands (aka: in the manpage) and finally a common block referring to
even more manpages. In exchange options are completely omitted from the
output as well as deprecated or obscure commands. (Better) Information
about them is available in the manpages anyway and the few options which
were listed before were also the least interesting ones (-o -c -q and co
are hardly of interest for someone totally new looking to find info by
asking for help and anyone with a bit of experience doesn't need this
short list. Those would need a list of options applying to the command
they call, but they are too numerous and command specific to list them
sanely in this context.

2 files changed, 53 insertions, 17 deletions

diff --git a/apt-private/private-cmndline.cc b/apt-private/private-cmndline.cc
index 4e80314f1..4231c4f0e 100644
--- a/apt-private/private-cmndline.cc
+++ b/apt-private/private-cmndline.cc
@@ -7,14 +7,17 @@
 #include <apt-pkg/pkgsystem.h>
 #include <apt-pkg/init.h>
 #include <apt-pkg/error.h>
+#include <apt-pkg/strutl.h>
 
 #include <apt-private/private-cmndline.h>
 
-#include <vector>
 #include <stdarg.h>
 #include <string.h>
 #include <stdlib.h>
 
+#include <vector>
+#include <iomanip>
+
 #include <apti18n.h>
 									/*}}}*/
 
@@ -362,23 +365,57 @@ std::vector<CommandLine::Args> getCommandArgs(APT_CMD const Program, char const
 									/*}}}*/
 #undef CmdMatches
 #undef addArg
-static bool ShowCommonHelp(APT_CMD const Binary, CommandLine &CmdL, aptDispatchWithHelp const * Cmds)/*{{{*/
+static void ShowHelpListCommands(std::vector<aptDispatchWithHelp> const &Cmds)/*{{{*/
 {
-   std::cout << PACKAGE << " " << PACKAGE_VERSION << " (" << COMMON_ARCH << ")" << std::endl;
-   if (_config->FindB("version") == true && Binary != APT_CMD::APT_GET)
-      return true;
-   return ShowHelp(CmdL, Cmds);
+   if (Cmds.empty() || Cmds[0].Match == nullptr)
+      return;
+   std::cout << std::endl << _("Most used commands:") << std::endl;
+   for (auto const &c: Cmds)
+   {
+      if (c.Help == nullptr)
+	 continue;
+      std::cout << "  " << c.Match << " - " << c.Help << std::endl;
+   }
 }
 									/*}}}*/
-void ShowHelpListCommands(aptDispatchWithHelp const * Cmds)		/*{{{*/
+static bool ShowCommonHelp(APT_CMD const Binary, CommandLine &CmdL, std::vector<aptDispatchWithHelp> const &Cmds)/*{{{*/
 {
-   std::cout << _("Commands:") << std::endl;
-   for (; Cmds->Handler != nullptr; ++Cmds)
+   std::cout << PACKAGE << " " << PACKAGE_VERSION << " (" << COMMON_ARCH << ")" << std::endl;
+   if (_config->FindB("version") == true && Binary != APT_CMD::APT_GET)
+      return true;
+   if (ShowHelp(CmdL) == false)
+      return false;
+   if (_config->FindB("version") == true || Binary == APT_CMD::APT_FTPARCHIVE)
+      return true;
+   ShowHelpListCommands(Cmds);
+   std::cout << std::endl;
+   char const * cmd = nullptr;
+   switch (Binary)
    {
-      if (Cmds->Help == nullptr)
-	 continue;
-      std::cout << "  " << Cmds->Match << " - " << Cmds->Help << std::endl;
+      case APT_CMD::APT: cmd = "apt(8)"; break;
+      case APT_CMD::APT_CACHE: cmd = "apt-cache(8)"; break;
+      case APT_CMD::APT_CDROM: cmd = "apt-cdrom(8)"; break;
+      case APT_CMD::APT_CONFIG: cmd = "apt-config(8)"; break;
+      case APT_CMD::APT_EXTRACTTEMPLATES: cmd = "apt-extracttemplates(1)"; break;
+      case APT_CMD::APT_FTPARCHIVE: cmd = "apt-ftparchive(1)"; break;
+      case APT_CMD::APT_GET: cmd = "apt-get(8)"; break;
+      case APT_CMD::APT_HELPER: cmd = nullptr; break;
+      case APT_CMD::APT_INTERNAL_SOLVER: cmd = nullptr; break;
+      case APT_CMD::APT_MARK: cmd = "apt-mark(8)"; break;
+      case APT_CMD::APT_SORTPKG: cmd = "apt-sortpkgs(1)"; break;
    }
+   if (cmd != nullptr)
+      ioprintf(std::cout, _("See %s for more information about the available commands."), cmd);
+   std::cout << std::endl <<
+      _("Configuration options and syntax is detailed in apt.conf(5).\n"
+	    "Information about how to configure sources can be found in sources.list(5).\n"
+	    "Package and version choices can be expressed via apt_preferences(5).\n"
+	    "Security details are available in apt-secure(8).\n");
+   if (Binary == APT_CMD::APT_GET || Binary == APT_CMD::APT)
+      std::cout << std::right << std::setw(70) << _("This APT has Super Cow Powers.") << std::endl;
+   else if (Binary == APT_CMD::APT_HELPER)
+      std::cout << std::right << std::setw(70) << _("This APT helper has Super Meep Powers.") << std::endl;
+   return true;
 }
 									/*}}}*/
 static void BinarySpecificConfiguration(char const * const Binary)	/*{{{*/
@@ -440,7 +477,7 @@ std::vector<CommandLine::Dispatch> ParseCommandLine(CommandLine &CmdL, APT_CMD c
        (Sys != NULL && pkgInitSystem(*_config, *Sys) == false))
    {
       if (_config->FindB("version") == true)
-	 ShowCommonHelp(Binary, CmdL, CmdsWithHelp.data());
+	 ShowCommonHelp(Binary, CmdL, CmdsWithHelp);
 
       _error->DumpErrors();
       exit(100);
@@ -450,12 +487,12 @@ std::vector<CommandLine::Dispatch> ParseCommandLine(CommandLine &CmdL, APT_CMD c
    if (_config->FindB("help") == true || _config->FindB("version") == true ||
 	 (CmdL.FileSize() > 0 && strcmp(CmdL.FileList[0], "help") == 0))
    {
-      ShowCommonHelp(Binary, CmdL, CmdsWithHelp.data());
+      ShowCommonHelp(Binary, CmdL, CmdsWithHelp);
       exit(0);
    }
    if (Cmds.empty() == false && CmdL.FileSize() == 0)
    {
-      ShowCommonHelp(Binary, CmdL, CmdsWithHelp.data());
+      ShowCommonHelp(Binary, CmdL, CmdsWithHelp);
       exit(1);
    }
    return Cmds;
diff --git a/apt-private/private-cmndline.h b/apt-private/private-cmndline.h
index 6a6885a33..819eb77cc 100644
--- a/apt-private/private-cmndline.h
+++ b/apt-private/private-cmndline.h
@@ -23,6 +23,7 @@ enum class APT_CMD {
    APT_SORTPKG,
 };
 
+bool ShowHelp(CommandLine &CmdL);
 struct aptDispatchWithHelp
 {
    const char *Match;
@@ -30,9 +31,7 @@ struct aptDispatchWithHelp
    const char *Help;
 };
 std::vector<aptDispatchWithHelp> GetCommands();
-bool ShowHelp(CommandLine &CmdL, aptDispatchWithHelp const * Cmds);
 
-APT_PUBLIC void ShowHelpListCommands(aptDispatchWithHelp const * Cmds);
 APT_PUBLIC std::vector<CommandLine::Dispatch> ParseCommandLine(CommandLine &CmdL, APT_CMD const Binary,
       Configuration * const * const Cnf, pkgSystem ** const Sys, int const argc, const char * argv[]);
 APT_PUBLIC unsigned short DispatchCommandLine(CommandLine &CmdL, std::vector<CommandLine::Dispatch> const &Cmds);