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, 106 insertions, 22 deletions

diff --git a/doc/apt-cache.8.xml b/doc/apt-cache.8.xml
index b649149af..a76eb1000 100644
--- a/doc/apt-cache.8.xml
+++ b/doc/apt-cache.8.xml
@@ -32,10 +32,16 @@
  &synopsis-command-apt-cache;
 
  <refsect1><title>Description</title>
-   <para><command>apt-cache</command> performs a variety of operations on APT's package 
-   cache. <command>apt-cache</command> does not manipulate the state of the system 
-   but does provide operations to search and generate interesting output 
-   from the package metadata.</para>
+    <para>
+       <command>apt-cache</command> performs a variety of operations on APT's
+       package cache. <command>apt-cache</command> does not manipulate the
+       state of the system but does provide operations to search and generate
+       interesting output from the package metadata. The metadata is acquired
+       and updated via the 'update' command of e.g. <command>apt-get</command>,
+       so that it can be outdated if the last update is too long ago, but in
+       exchange <command>apt-cache</command> works independently of the
+       availability of the configured sources (e.g. offline).
+    </para>
 
    <para>Unless the <option>-h</option>, or <option>--help</option> option is given, one of the
    commands below must be present.</para>
diff --git a/doc/po/apt-doc.pot b/doc/po/apt-doc.pot
index c308771f2..1aaca1f3d 100644
--- a/doc/po/apt-doc.pot
+++ b/doc/po/apt-doc.pot
@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: apt-doc 1.1~exp14\n"
 "Report-Msgid-Bugs-To: APT Development Team <deity@lists.debian.org>\n"
-"POT-Creation-Date: 2015-10-22 16:34+0200\n"
+"POT-Creation-Date: 2015-10-27 10:30+0100\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@li.org>\n"
@@ -1445,7 +1445,11 @@ msgid ""
 "<command>apt-cache</command> performs a variety of operations on APT's "
 "package cache. <command>apt-cache</command> does not manipulate the state of "
 "the system but does provide operations to search and generate interesting "
-"output from the package metadata."
+"output from the package metadata. The metadata is acquired and updated via "
+"the 'update' command of e.g. <command>apt-get</command>, so that it can be "
+"outdated if the last update is too long ago, but in exchange "
+"<command>apt-cache</command> works independently of the availability of the "
+"configured sources (e.g. offline)."
 msgstr ""
 
 #. type: Content of: <refentry><refsect1><variablelist><varlistentry><listitem><para>
diff --git a/doc/po/de.po b/doc/po/de.po
index b8d848781..9e79c0364 100644
--- a/doc/po/de.po
+++ b/doc/po/de.po
@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: apt-doc 1.0.8\n"
 "Report-Msgid-Bugs-To: APT Development Team <deity@lists.debian.org>\n"
-"POT-Creation-Date: 2015-10-22 16:34+0200\n"
+"POT-Creation-Date: 2015-10-27 10:30+0100\n"
 "PO-Revision-Date: 2014-09-14 14:46+0200\n"
 "Last-Translator: Chris Leick <c.leick@vollbio.de>\n"
 "Language-Team: German <debian-l10n-german@lists.debian.org>\n"
@@ -2009,11 +2009,21 @@ msgstr "den APT-Zwischenspeicher abfragen"
 
 #. type: Content of: <refentry><refsect1><para>
 #: apt-cache.8.xml
+#, fuzzy
+#| msgid ""
+#| "<command>apt-cache</command> performs a variety of operations on APT's "
+#| "package cache. <command>apt-cache</command> does not manipulate the state "
+#| "of the system but does provide operations to search and generate "
+#| "interesting output from the package metadata."
 msgid ""
 "<command>apt-cache</command> performs a variety of operations on APT's "
 "package cache. <command>apt-cache</command> does not manipulate the state of "
 "the system but does provide operations to search and generate interesting "
-"output from the package metadata."
+"output from the package metadata. The metadata is acquired and updated via "
+"the 'update' command of e.g. <command>apt-get</command>, so that it can be "
+"outdated if the last update is too long ago, but in exchange <command>apt-"
+"cache</command> works independently of the availability of the configured "
+"sources (e.g. offline)."
 msgstr ""
 "<command>apt-cache</command> führt eine Vielzahl von Operationen auf dem "
 "Paketzwischenspeicher von APT durch. <command>apt-cache</command> "
diff --git a/doc/po/es.po b/doc/po/es.po
index 8dbfecd58..9894c7675 100644
--- a/doc/po/es.po
+++ b/doc/po/es.po
@@ -38,7 +38,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: apt-doc 1.0.5\n"
 "Report-Msgid-Bugs-To: APT Development Team <deity@lists.debian.org>\n"
-"POT-Creation-Date: 2015-10-22 16:34+0200\n"
+"POT-Creation-Date: 2015-10-27 10:30+0100\n"
 "PO-Revision-Date: 2014-07-04 01:31+0200\n"
 "Last-Translator: Omar Campagne <ocampagne@gmail.com>\n"
 "Language-Team: Debian l10n Spanish <debian-l10n-spanish@lists.debian.org>\n"
@@ -2087,11 +2087,21 @@ msgstr "Realiza consultas al caché de APT"
 
 #. type: Content of: <refentry><refsect1><para>
 #: apt-cache.8.xml
+#, fuzzy
+#| msgid ""
+#| "<command>apt-cache</command> performs a variety of operations on APT's "
+#| "package cache. <command>apt-cache</command> does not manipulate the state "
+#| "of the system but does provide operations to search and generate "
+#| "interesting output from the package metadata."
 msgid ""
 "<command>apt-cache</command> performs a variety of operations on APT's "
 "package cache. <command>apt-cache</command> does not manipulate the state of "
 "the system but does provide operations to search and generate interesting "
-"output from the package metadata."
+"output from the package metadata. The metadata is acquired and updated via "
+"the 'update' command of e.g. <command>apt-get</command>, so that it can be "
+"outdated if the last update is too long ago, but in exchange <command>apt-"
+"cache</command> works independently of the availability of the configured "
+"sources (e.g. offline)."
 msgstr ""
 "<command>apt-cache</command> realiza una serie de operaciones sobre la caché "
 "(registro o lista) de paquetes de APT. <command>apt-cache</command> no "
diff --git a/doc/po/fr.po b/doc/po/fr.po
index 67b759120..eb79e8324 100644
--- a/doc/po/fr.po
+++ b/doc/po/fr.po
@@ -11,7 +11,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: apt-doc 1.0.5\n"
 "Report-Msgid-Bugs-To: APT Development Team <deity@lists.debian.org>\n"
-"POT-Creation-Date: 2015-10-22 16:34+0200\n"
+"POT-Creation-Date: 2015-10-27 10:30+0100\n"
 "PO-Revision-Date: 2014-11-15 17:26+0100\n"
 "Last-Translator: Jean-Pierre Giraud <jean-pierregiraud@neuf.fr>\n"
 "Language-Team: French <debian-l10n-french@lists.debian.org>\n"
@@ -2004,11 +2004,21 @@ msgstr "recherche dans le cache d'APT"
 
 #. type: Content of: <refentry><refsect1><para>
 #: apt-cache.8.xml
+#, fuzzy
+#| msgid ""
+#| "<command>apt-cache</command> performs a variety of operations on APT's "
+#| "package cache. <command>apt-cache</command> does not manipulate the state "
+#| "of the system but does provide operations to search and generate "
+#| "interesting output from the package metadata."
 msgid ""
 "<command>apt-cache</command> performs a variety of operations on APT's "
 "package cache. <command>apt-cache</command> does not manipulate the state of "
 "the system but does provide operations to search and generate interesting "
-"output from the package metadata."
+"output from the package metadata. The metadata is acquired and updated via "
+"the 'update' command of e.g. <command>apt-get</command>, so that it can be "
+"outdated if the last update is too long ago, but in exchange <command>apt-"
+"cache</command> works independently of the availability of the configured "
+"sources (e.g. offline)."
 msgstr ""
 "<command>apt-cache</command> réalise différentes opérations sur le cache de "
 "paquet d'APT. <command>apt-cache</command> ne manipule pas l'état du système "
diff --git a/doc/po/it.po b/doc/po/it.po
index c97b09b35..7157c4bb2 100644
--- a/doc/po/it.po
+++ b/doc/po/it.po
@@ -10,7 +10,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: apt-doc 1.0.5\n"
 "Report-Msgid-Bugs-To: APT Development Team <deity@lists.debian.org>\n"
-"POT-Creation-Date: 2015-10-22 16:34+0200\n"
+"POT-Creation-Date: 2015-10-27 10:30+0100\n"
 "PO-Revision-Date: 2015-01-27 14:11+0200\n"
 "Last-Translator: Beatrice Torracca <beatricet@libero.it>\n"
 "Language-Team: Italian <debian-l10n-italian@lists.debian.org>\n"
@@ -2049,11 +2049,21 @@ msgstr "interroga la cache di APT"
 
 #. type: Content of: <refentry><refsect1><para>
 #: apt-cache.8.xml
+#, fuzzy
+#| msgid ""
+#| "<command>apt-cache</command> performs a variety of operations on APT's "
+#| "package cache. <command>apt-cache</command> does not manipulate the state "
+#| "of the system but does provide operations to search and generate "
+#| "interesting output from the package metadata."
 msgid ""
 "<command>apt-cache</command> performs a variety of operations on APT's "
 "package cache. <command>apt-cache</command> does not manipulate the state of "
 "the system but does provide operations to search and generate interesting "
-"output from the package metadata."
+"output from the package metadata. The metadata is acquired and updated via "
+"the 'update' command of e.g. <command>apt-get</command>, so that it can be "
+"outdated if the last update is too long ago, but in exchange <command>apt-"
+"cache</command> works independently of the availability of the configured "
+"sources (e.g. offline)."
 msgstr ""
 "<command>apt-cache</command> esegue una varietà di operazioni sulla cache "
 "dei pacchetti di APT. <command>apt-cache</command> non manipola lo stato del "
diff --git a/doc/po/ja.po b/doc/po/ja.po
index 7aaff2e79..7de7203e3 100644
--- a/doc/po/ja.po
+++ b/doc/po/ja.po
@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: apt-doc 1.0.6\n"
 "Report-Msgid-Bugs-To: APT Development Team <deity@lists.debian.org>\n"
-"POT-Creation-Date: 2015-10-22 16:34+0200\n"
+"POT-Creation-Date: 2015-10-27 10:30+0100\n"
 "PO-Revision-Date: 2014-07-10 19:52+0900\n"
 "Last-Translator: KURASAWA Nozomu <nabetaro@debian.or.jp>\n"
 "Language-Team: Debian Japanese List <debian-japanese@lists.debian.org>\n"
@@ -1988,11 +1988,21 @@ msgstr "APT キャッシュへの問い合わせ"
 
 #. type: Content of: <refentry><refsect1><para>
 #: apt-cache.8.xml
+#, fuzzy
+#| msgid ""
+#| "<command>apt-cache</command> performs a variety of operations on APT's "
+#| "package cache. <command>apt-cache</command> does not manipulate the state "
+#| "of the system but does provide operations to search and generate "
+#| "interesting output from the package metadata."
 msgid ""
 "<command>apt-cache</command> performs a variety of operations on APT's "
 "package cache. <command>apt-cache</command> does not manipulate the state of "
 "the system but does provide operations to search and generate interesting "
-"output from the package metadata."
+"output from the package metadata. The metadata is acquired and updated via "
+"the 'update' command of e.g. <command>apt-get</command>, so that it can be "
+"outdated if the last update is too long ago, but in exchange <command>apt-"
+"cache</command> works independently of the availability of the configured "
+"sources (e.g. offline)."
 msgstr ""
 "<command>apt-cache</command> は APT のパッケージキャッシュに対して、さまざま"
 "な操作を行います。<command>apt-cache</command> は、システム状態の操作は行いま"
diff --git a/doc/po/pl.po b/doc/po/pl.po
index 37cf2fb5f..f1e898a02 100644
--- a/doc/po/pl.po
+++ b/doc/po/pl.po
@@ -11,7 +11,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: apt-doc 1.0.5\n"
 "Report-Msgid-Bugs-To: APT Development Team <deity@lists.debian.org>\n"
-"POT-Creation-Date: 2015-10-22 16:34+0200\n"
+"POT-Creation-Date: 2015-10-27 10:30+0100\n"
 "PO-Revision-Date: 2014-07-04 02:13+0200\n"
 "Last-Translator: Robert Luberda <robert@debian.org>\n"
 "Language-Team: Polish <manpages-pl-list@lists.sourceforge.net>\n"
@@ -2088,11 +2088,21 @@ msgstr "odpytanie bufora APT"
 #
 #. type: Content of: <refentry><refsect1><para>
 #: apt-cache.8.xml
+#, fuzzy
+#| msgid ""
+#| "<command>apt-cache</command> performs a variety of operations on APT's "
+#| "package cache. <command>apt-cache</command> does not manipulate the state "
+#| "of the system but does provide operations to search and generate "
+#| "interesting output from the package metadata."
 msgid ""
 "<command>apt-cache</command> performs a variety of operations on APT's "
 "package cache. <command>apt-cache</command> does not manipulate the state of "
 "the system but does provide operations to search and generate interesting "
-"output from the package metadata."
+"output from the package metadata. The metadata is acquired and updated via "
+"the 'update' command of e.g. <command>apt-get</command>, so that it can be "
+"outdated if the last update is too long ago, but in exchange <command>apt-"
+"cache</command> works independently of the availability of the configured "
+"sources (e.g. offline)."
 msgstr ""
 "<command>apt-cache</command> wykonuje różnorodne operacje na buforze (cache) "
 "pakietów programu APT. <command>apt-cache</command> nie zmienia stanu "
diff --git a/doc/po/pt.po b/doc/po/pt.po
index eae77d68d..a946970c9 100644
--- a/doc/po/pt.po
+++ b/doc/po/pt.po
@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: apt-doc 1.0.7\n"
 "Report-Msgid-Bugs-To: APT Development Team <deity@lists.debian.org>\n"
-"POT-Creation-Date: 2015-10-22 16:34+0200\n"
+"POT-Creation-Date: 2015-10-27 10:30+0100\n"
 "PO-Revision-Date: 2014-08-29 00:34+0100\n"
 "Last-Translator: Américo Monteiro <a_monteiro@gmx.com>\n"
 "Language-Team: Portuguese <traduz@debianpt.org>\n"
@@ -2026,11 +2026,21 @@ msgstr "pesquisa a cache do APT"
 
 #. type: Content of: <refentry><refsect1><para>
 #: apt-cache.8.xml
+#, fuzzy
+#| msgid ""
+#| "<command>apt-cache</command> performs a variety of operations on APT's "
+#| "package cache. <command>apt-cache</command> does not manipulate the state "
+#| "of the system but does provide operations to search and generate "
+#| "interesting output from the package metadata."
 msgid ""
 "<command>apt-cache</command> performs a variety of operations on APT's "
 "package cache. <command>apt-cache</command> does not manipulate the state of "
 "the system but does provide operations to search and generate interesting "
-"output from the package metadata."
+"output from the package metadata. The metadata is acquired and updated via "
+"the 'update' command of e.g. <command>apt-get</command>, so that it can be "
+"outdated if the last update is too long ago, but in exchange <command>apt-"
+"cache</command> works independently of the availability of the configured "
+"sources (e.g. offline)."
 msgstr ""
 "<command>apt-cache</command> executa uma variedade de operações na cache de "
 "pacotes do APT. <command>apt-cache</command> não manipula o estado do "
diff --git a/doc/po/pt_BR.po b/doc/po/pt_BR.po
index a96dc5e3c..b5797af9b 100644
--- a/doc/po/pt_BR.po
+++ b/doc/po/pt_BR.po
@@ -9,7 +9,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: apt-doc 1.0.5\n"
 "Report-Msgid-Bugs-To: APT Development Team <deity@lists.debian.org>\n"
-"POT-Creation-Date: 2015-10-22 16:34+0200\n"
+"POT-Creation-Date: 2015-10-27 10:30+0100\n"
 "PO-Revision-Date: 2004-09-20 17:02+0000\n"
 "Last-Translator: André Luís Lopes <andrelop@debian.org>\n"
 "Language-Team: <debian-l10n-portuguese@lists.debian.org>\n"
@@ -1422,7 +1422,11 @@ msgid ""
 "<command>apt-cache</command> performs a variety of operations on APT's "
 "package cache. <command>apt-cache</command> does not manipulate the state of "
 "the system but does provide operations to search and generate interesting "
-"output from the package metadata."
+"output from the package metadata. The metadata is acquired and updated via "
+"the 'update' command of e.g. <command>apt-get</command>, so that it can be "
+"outdated if the last update is too long ago, but in exchange <command>apt-"
+"cache</command> works independently of the availability of the configured "
+"sources (e.g. offline)."
 msgstr ""
 
 #. type: Content of: <refentry><refsect1><variablelist><varlistentry><listitem><para>