add man-page, improve option, use --with-new-pkgs as the flag

apt-private/private-cmndline.cc

@@ -125,7 +125,8 @@ bool addArgumentsAPTGet(std::vector<CommandLine::Args> &Args, char const * const
       addArg(0, "solver", "APT::Solver", CommandLine::HasArg);
       if (CmdMatches("upgrade"))
       {
-	 addArg(0, "allow-new", "APT::Get::UpgradeAllowNew", 0);
+         addArg(0, "allow-new", "APT::Get::Upgrade-Allow-New", 
+                CommandLine::Boolean);
       }
    }
    else if (CmdMatches("update"))
@@ -163,9 +164,6 @@ bool addArgumentsAPTGet(std::vector<CommandLine::Args> &Args, char const * const
       addArg('s', "no-act", "APT::Get::Simulate", 0);
    }
 
-   if (CmdMatches("upgrade"))
-      addArg(0, "allow-new", "APT::Get::UpgradeAllowNew", CommandLine::Boolean);
-
    // FIXME: move to the correct command(s)
    addArg('d',"download-only","APT::Get::Download-Only",0);
    addArg('y',"yes","APT::Get::Assume-Yes",0);

cmdline/apt-get.cc

@@ -1627,7 +1627,7 @@ void SigWinch(int)
 
 bool DoUpgrade(CommandLine &CmdL)
 {
-   if (_config->FindB("APT::Get::UpgradeAllowNew", false) == true)
+   if (_config->FindB("APT::Get::Upgrade-Allow-New", false) == true)
       return DoUpgradeWithAllowNewPackages(CmdL);
    else
       return DoUpgradeNoNewPackages(CmdL);

doc/apt-get.8.xml

@@ -389,6 +389,18 @@
      Configuration Item: <literal>APT::Ignore-Hold</literal>.</para></listitem>
      </varlistentry>
 
+     <varlistentry><term><option>--with-new-pkgs</option></term>
+     <listitem><para>Allow installing new packages when used in
+     conjunction with <literal>upgrade</literal>.  This is useful if
+     the update of a installed package requires new dependencies to be
+     installed. Instead of holding the package back <literal>upgrade</literal>
+     will upgrade the package and install the new dependencies. Note that
+     <literal>upgrade</literal> with this option will never remove packages,
+     only allow adding new ones.
+     Configuration Item:  <literal>APT::Get::Upgrade-Allow-New</literal>.
+     </para></listitem>
+     </varlistentry>
+
      <varlistentry><term><option>--no-upgrade</option></term>
      <listitem><para>Do not upgrade packages; when used in conjunction with <literal>install</literal>,
      <literal>no-upgrade</literal> will prevent packages on the command line