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.

10 files changed, 56 insertions, 131 deletions

diff --git a/cmdline/apt-cache.cc b/cmdline/apt-cache.cc
index 465911570..dd1488568 100644
--- a/cmdline/apt-cache.cc
+++ b/cmdline/apt-cache.cc
@@ -1202,26 +1202,18 @@ static bool GenCaches(CommandLine &)
    return CacheFile.BuildCaches(&Progress, true);
 }
 									/*}}}*/
-bool ShowHelp(CommandLine &, aptDispatchWithHelp const * Cmds)		/*{{{*/
+bool ShowHelp(CommandLine &)						/*{{{*/
 {
    std::cout <<
     _("Usage: apt-cache [options] command\n"
       "       apt-cache [options] show pkg1 [pkg2 ...]\n"
       "\n"
-      "apt-cache is a low-level tool used to query information\n"
-      "from APT's binary cache files\n")
-    << std::endl;
-   ShowHelpListCommands(Cmds);
-   std::cout << std::endl
-    << _("Options:\n"
-      "  -h   This help text.\n"
-      "  -p=? The package cache.\n"
-      "  -s=? The source cache.\n"
-      "  -q   Disable progress indicator.\n"
-      "  -i   Show only important deps for the unmet command.\n"
-      "  -c=? Read this configuration file\n"
-      "  -o=? Set an arbitrary configuration option, eg -o dir::cache=/tmp\n"
-      "See the apt-cache(8) and apt.conf(5) manual pages for more information.\n");
+      "apt-cache queries and displays available information about installed\n"
+      "as well as installable packages. It works exclusively on the data\n"
+      "acquired via the 'update' command of e.g. apt-get to the local cache.\n"
+      "The displayed information can therefore be outdated if the last update\n"
+      "is too long ago, but in exchange apt-cache works independently of the\n"
+      "availability of the configured sources (e.g. offline).\n");
    return true;
 }
 									/*}}}*/
diff --git a/cmdline/apt-cdrom.cc b/cmdline/apt-cdrom.cc
index 00895863b..4a24f198c 100644
--- a/cmdline/apt-cdrom.cc
+++ b/cmdline/apt-cdrom.cc
@@ -203,28 +203,14 @@ static bool DoIdent(CommandLine &)
    return AddOrIdent(false);
 }
 									/*}}}*/
-bool ShowHelp(CommandLine &, aptDispatchWithHelp const * Cmds)		/*{{{*/
+bool ShowHelp(CommandLine &)						/*{{{*/
 {
    std::cout <<
       _("Usage: apt-cdrom [options] command\n"
       "\n"
-      "apt-cdrom is a tool to add CDROM's to APT's source list. The\n"
-      "CDROM mount point and device information is taken from apt.conf,\n"
-      "udev and /etc/fstab.\n")
-      << std::endl;
-   ShowHelpListCommands(Cmds);
-   std::cout << std::endl <<
-      _("Options:\n"
-      "  -h   This help text\n"
-      "  -d   CD-ROM mount point\n"
-      "  -r   Rename a recognized CD-ROM\n"
-      "  -m   No mounting\n"
-      "  -f   Fast mode, don't check package files\n"
-      "  -a   Thorough scan mode\n"
-      "  --no-auto-detect Do not try to auto detect drive and mount point\n"
-      "  -c=? Read this configuration file\n"
-      "  -o=? Set an arbitrary configuration option, eg -o dir::cache=/tmp\n"
-      "See fstab(5)\n");
+      "apt-cdrom is used to add CDROM's, USB flashdrives and other removable\n"
+      "media types as package sources to APT. The mount point and device\n"
+      "information is taken from apt.conf(5), udev(7) and fstab(5).\n");
    return true;
 }
 									/*}}}*/
diff --git a/cmdline/apt-config.cc b/cmdline/apt-config.cc
index eb096440a..8442161d3 100644
--- a/cmdline/apt-config.cc
+++ b/cmdline/apt-config.cc
@@ -76,19 +76,13 @@ static bool DoDump(CommandLine &CmdL)
    return true;
 }
 									/*}}}*/
-bool ShowHelp(CommandLine &, aptDispatchWithHelp const * Cmds)		/*{{{*/
+bool ShowHelp(CommandLine &)						/*{{{*/
 {
    std::cout <<
       _("Usage: apt-config [options] command\n"
       "\n"
-      "apt-config is a simple tool to read the APT config file\n")
-      << std::endl;
-   ShowHelpListCommands(Cmds);
-   std::cout << std::endl <<
-      _("Options:\n"
-      "  -h   This help text.\n"
-      "  -c=? Read this configuration file\n"
-      "  -o=? Set an arbitrary configuration option, eg -o dir::cache=/tmp\n");
+      "apt-config is an interface to the configuration settings used by\n"
+      "all APT tools to be used mainly in debugging and shell scripting.\n");
    return true;
 }
 									/*}}}*/
diff --git a/cmdline/apt-extracttemplates.cc b/cmdline/apt-extracttemplates.cc
index b63f2ff16..0e60ff5fb 100644
--- a/cmdline/apt-extracttemplates.cc
+++ b/cmdline/apt-extracttemplates.cc
@@ -215,19 +215,14 @@ bool DebFile::ParseInfo()
 	return true;
 }
 									/*}}}*/
-bool ShowHelp(CommandLine &, aptDispatchWithHelp const *)		/*{{{*/
+bool ShowHelp(CommandLine &)						/*{{{*/
 {
 	cout <<
 		_("Usage: apt-extracttemplates file1 [file2 ...]\n"
 		"\n"
-		"apt-extracttemplates is a tool to extract config and template info\n"
-		"from debian packages\n"
-		"\n"
-		"Options:\n"
-	        "  -h   This help text\n"
-		"  -t   Set the temp dir\n"
-		"  -c=? Read this configuration file\n"
-		"  -o=? Set an arbitrary configuration option, eg -o dir::cache=/tmp\n");
+		"apt-extracttemplates is used to extract config and template files\n"
+		"from debian packages. It is used mainly by debconf(1) to prompt for\n"
+		"configuration questions before installation of packages.\n");
 	return true;
 }
 									/*}}}*/
diff --git a/cmdline/apt-get.cc b/cmdline/apt-get.cc
index 9ffb7b1ee..5002ec1b8 100644
--- a/cmdline/apt-get.cc
+++ b/cmdline/apt-get.cc
@@ -343,7 +343,7 @@ static bool DoIndexTargets(CommandLine &CmdL)
    return true;
 }
 									/*}}}*/
-bool ShowHelp(CommandLine &, aptDispatchWithHelp const * Cmds)		/*{{{*/
+bool ShowHelp(CommandLine &)						/*{{{*/
 {
    if (_config->FindB("version") == true)
    {
@@ -371,50 +371,31 @@ bool ShowHelp(CommandLine &, aptDispatchWithHelp const * Cmds)		/*{{{*/
 	       cout << "Pkg:  " << Sys->Label << " (Priority " << Sys->Score(*_config) << ")" << endl;
 	 }
       }
-      
+
       for (unsigned I = 0; I != pkgSourceList::Type::GlobalListLen; I++)
       {
 	 pkgSourceList::Type *Type = pkgSourceList::Type::GlobalList[I];
 	 cout << " S.L: '" << Type->Name << "' " << Type->Label << endl;
-      }      
-      
+      }
+
       for (unsigned I = 0; I != pkgIndexFile::Type::GlobalListLen; I++)
       {
 	 pkgIndexFile::Type *Type = pkgIndexFile::Type::GlobalList[I];
 	 cout << " Idx: " << Type->Label << endl;
-      }      
-      
+      }
+
       return true;
    }
 
    std::cout <<
-    _("Usage: apt-get [options] command\n"
-      "       apt-get [options] install|remove pkg1 [pkg2 ...]\n"
-      "       apt-get [options] source pkg1 [pkg2 ...]\n"
-      "\n"
-      "apt-get is a simple command line interface for downloading and\n"
-      "installing packages. The most frequently used commands are update\n"
-      "and install.\n")
-      << std::endl;
-   ShowHelpListCommands(Cmds);
-   std::cout << std::endl <<
-      _("Options:\n"
-      "  -h  This help text.\n"
-      "  -q  Loggable output - no progress indicator\n"
-      "  -qq No output except for errors\n"
-      "  -d  Download only - do NOT install or unpack archives\n"
-      "  -s  No-act. Perform ordering simulation\n"
-      "  -y  Assume Yes to all queries and do not prompt\n"
-      "  -f  Attempt to correct a system with broken dependencies in place\n"
-      "  -m  Attempt to continue if archives are unlocatable\n"
-      "  -u  Show a list of upgraded packages as well\n"
-      "  -b  Build the source package after fetching it\n"
-      "  -V  Show verbose version numbers\n"
-      "  -c=? Read this configuration file\n"
-      "  -o=? Set an arbitrary configuration option, eg -o dir::cache=/tmp\n"
-      "See the apt-get(8), sources.list(5) and apt.conf(5) manual\n"
-      "pages for more information and options.\n"
-      "                       This APT has Super Cow Powers.\n");
+      _("Usage: apt-get [options] command\n"
+	    "       apt-get [options] install|remove pkg1 [pkg2 ...]\n"
+	    "       apt-get [options] source pkg1 [pkg2 ...]\n"
+	    "\n"
+	    "apt-get is a command line interface for retrieval of packages\n"
+	    "and information about them from authenticated sources and\n"
+	    "for installation, upgrade and removal of packages together\n"
+	    "with their dependencies.\n");
    return true;
 }
 									/*}}}*/
diff --git a/cmdline/apt-helper.cc b/cmdline/apt-helper.cc
index be6c2881a..1c67594b9 100644
--- a/cmdline/apt-helper.cc
+++ b/cmdline/apt-helper.cc
@@ -105,17 +105,14 @@ static bool DoSrvLookup(CommandLine &CmdL)				/*{{{*/
    return true;
 }
 									/*}}}*/
-bool ShowHelp(CommandLine &, aptDispatchWithHelp const  * Cmds)		/*{{{*/
+bool ShowHelp(CommandLine &)						/*{{{*/
 {
    std::cout <<
-    _("Usage: apt-helper [options] command\n"
-      "       apt-helper [options] download-file uri target-path\n"
-      "\n"
-      "apt-helper is a internal helper for apt\n")
-    << std::endl;
-   ShowHelpListCommands(Cmds);
-   std::cout << std::endl <<
-      _("This APT helper has Super Meep Powers.") << std::endl;
+      _("Usage: apt-helper [options] command\n"
+	    "       apt-helper [options] download-file uri target-path\n"
+	    "\n"
+	    "apt-helper bundles a variety of commands for shell scripts to use\n"
+	    "e.g. the same proxy configuration or acquire system as APT would do.\n");
    return true;
 }
 									/*}}}*/
diff --git a/cmdline/apt-internal-solver.cc b/cmdline/apt-internal-solver.cc
index ae8c08bba..929fd6e27 100644
--- a/cmdline/apt-internal-solver.cc
+++ b/cmdline/apt-internal-solver.cc
@@ -41,19 +41,13 @@
 #include <apti18n.h>
 									/*}}}*/
 
-bool ShowHelp(CommandLine &, aptDispatchWithHelp const *)		/*{{{*/
+bool ShowHelp(CommandLine &)						/*{{{*/
 {
 	std::cout <<
 		_("Usage: apt-internal-solver\n"
 		"\n"
 		"apt-internal-solver is an interface to use the current internal\n"
-		"like an external resolver for the APT family for debugging or alike\n"
-		"\n"
-		"Options:\n"
-		"  -h  This help text.\n"
-		"  -q  Loggable output - no progress indicator\n"
-		"  -c=? Read this configuration file\n"
-		"  -o=? Set an arbitrary configuration option, eg -o dir::cache=/tmp\n");
+		"like an external resolver for the APT family for debugging or alike.\n");
 	return true;
 }
 									/*}}}*/
diff --git a/cmdline/apt-mark.cc b/cmdline/apt-mark.cc
index b06fcc0cc..66adfd268 100644
--- a/cmdline/apt-mark.cc
+++ b/cmdline/apt-mark.cc
@@ -280,26 +280,15 @@ static bool ShowSelection(CommandLine &CmdL)				/*{{{*/
    return true;
 }
 									/*}}}*/
-bool ShowHelp(CommandLine &, aptDispatchWithHelp const * Cmds)		/*{{{*/
+bool ShowHelp(CommandLine &)						/*{{{*/
 {
    std::cout <<
     _("Usage: apt-mark [options] {auto|manual} pkg1 [pkg2 ...]\n"
       "\n"
       "apt-mark is a simple command line interface for marking packages\n"
-      "as manually or automatically installed. It can also list marks.\n")
-    << std::endl;
-   ShowHelpListCommands(Cmds);
-   std::cout << std::endl
-   << _("Options:\n"
-      "  -h  This help text.\n"
-      "  -q  Loggable output - no progress indicator\n"
-      "  -qq No output except for errors\n"
-      "  -s  No-act. Just prints what would be done.\n"
-      "  -f  read/write auto/manual marking in the given file\n"
-      "  -c=? Read this configuration file\n"
-      "  -o=? Set an arbitrary configuration option, eg -o dir::cache=/tmp\n"
-      "See the apt-mark(8) and apt.conf(5) manual pages for more information.")
-      << std::endl;
+      "as manually or automatically installed. It is also possible to\n"
+      "manipulate the dpkg(1) selection states of packages with it.\n"
+      "It can also list all packages with or without a certain marking.\n");
    return true;
 }
 									/*}}}*/
diff --git a/cmdline/apt-sortpkgs.cc b/cmdline/apt-sortpkgs.cc
index f9aa7d728..5057ac626 100644
--- a/cmdline/apt-sortpkgs.cc
+++ b/cmdline/apt-sortpkgs.cc
@@ -132,19 +132,14 @@ static bool DoIt(string InFile)
    return true;
 }
 									/*}}}*/
-bool ShowHelp(CommandLine &, aptDispatchWithHelp const *)		/*{{{*/
+bool ShowHelp(CommandLine &)						/*{{{*/
 {
    std::cout <<
     _("Usage: apt-sortpkgs [options] file1 [file2 ...]\n"
       "\n"
-      "apt-sortpkgs is a simple tool to sort package files. The -s option is used\n"
-      "to indicate what kind of file it is.\n"
-      "\n"
-      "Options:\n"
-      "  -h   This help text\n"
-      "  -s   Use source file sorting\n"
-      "  -c=? Read this configuration file\n"
-      "  -o=? Set an arbitrary configuration option, eg -o dir::cache=/tmp\n");
+      "apt-sortpkgs is a simple tool to sort package information files.\n"
+      "It sorts by default by binary package information, but the -s option\n"
+      "can be used to switch to source package ordering instead.\n");
    return true;
 }
 									/*}}}*/
diff --git a/cmdline/apt.cc b/cmdline/apt.cc
index 368822d2d..761ad60db 100644
--- a/cmdline/apt.cc
+++ b/cmdline/apt.cc
@@ -40,14 +40,16 @@
 #include <apti18n.h>
 									/*}}}*/
 
-bool ShowHelp(CommandLine &, aptDispatchWithHelp const * Cmds)		/*{{{*/
+bool ShowHelp(CommandLine &)						/*{{{*/
 {
    std::cout <<
-    _("Usage: apt [options] command\n"
-      "\n"
-      "CLI for apt.\n")
-    << std::endl;
-   ShowHelpListCommands(Cmds);
+      _("Usage: apt [options] command\n"
+	    "\n"
+	    "apt is a commandline package manager and provides commands for\n"
+	    "searching and managing as well as querying information about packages.\n"
+	    "It provides the same functionality as the specialized APT tools,\n"
+	    "like apt-get and apt-cache, but enables options more suitable for\n"
+	    "interactive use by default.\n");
    return true;
 }
 									/*}}}*/