add "Script usage" section and bugfixes

1 files changed, 21 insertions, 9 deletions

diff --git a/doc/apt.8.xml b/doc/apt.8.xml
index bb1f6bb91..91e22b1ef 100644
--- a/doc/apt.8.xml
+++ b/doc/apt.8.xml
@@ -29,13 +29,15 @@
  <!-- Man page title -->
  <refnamediv>
     <refname>apt</refname>
-    <refpurpose>APT package -- command-line interface</refpurpose>
+    <refpurpose>command-line interface</refpurpose>
  </refnamediv>
 
  &synopsis-command-apt;
 
  <refsect1><title>Description</title>
-   <para><command>apt</command> is the command-line tool for handling packages. It provides a commandline interface for the package management of the system.
+   <para><command>apt</command> (Advanced Package Tool) is the
+   command-line tool for handling packages. It provides a commandline
+   interface for the package management of the system.
 
    See also &apt-get; and &apt-cache; for more low-level command options.
    </para>
@@ -122,26 +124,36 @@
    </variablelist>
  </refsect1>
 
+</refsect1>
+
  <refsect1><title>Differences to &apt-get;</title>
  <para>The <command>apt</command> command is meant to be pleasant for
  end users and does not need to be backward compatilbe like
  &apt-get;. Therefore some options are different:
  
  <itemizedlist>
-   <listitem>The option <literal>DPkgPM::Progress-Fancy</literal> is enabled.
+   <listitem>
+     <para>The option <literal>DPkgPM::Progress-Fancy</literal> is enabled.
+     </para>
    </listitem>
-   <listitem>The option <literal>APT::Color</literal> is enabled.
+   <listitem>
+     <para>The option <literal>APT::Color</literal> is enabled.
+     </para>
    </listitem>
-   <listitem>A new <literal>list</literal> command is available
-   similar to <literal>dpkg --list</literal>.
+   <listitem>
+     <para>A new <literal>list</literal> command is available
+     similar to <literal>dpkg --list</literal>.
+     </para>
    </listitem>
-   <listitem>The option <literal>upgrade</literal> has
-   <literal>--with-new-pkgs</literal> enabled by default.
+   <listitem>
+     <para>The option <literal>upgrade</literal> has
+     <literal>--with-new-pkgs</literal> enabled by default.
+     </para>
    </listitem>
 
  </itemizedlist>
-
  </para>
+
  </refsect1>
 
  <refsect1><title>See Also</title>