merged from donkults experimental branch

22 files changed, 238 insertions, 246 deletions

diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
index 43d961443..cf79aff85 100644
--- a/doc/Doxyfile.in
+++ b/doc/Doxyfile.in
@@ -31,7 +31,7 @@ PROJECT_NAME           = @PACKAGE@
 # This could be handy for archiving the generated documentation or
 # if some version control system is used.
 
-PROJECT_NUMBER         = @VERSION@
+PROJECT_NUMBER         = @PACKAGE_VERSION@
 
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute)
 # base path where the generated documentation will be put.
diff --git a/doc/apt-cache.8.xml b/doc/apt-cache.8.xml
index 1393de015..42d700c82 100644
--- a/doc/apt-cache.8.xml
+++ b/doc/apt-cache.8.xml
@@ -33,34 +33,8 @@
     <refpurpose>query the APT cache</refpurpose>
  </refnamediv>
 
- <!-- Arguments -->
- <refsynopsisdiv>
-   <cmdsynopsis>
-      <command>apt-cache</command>
-      <arg><option>-hvsn</option></arg>
-      <arg><option>-o=<replaceable>config string</replaceable></option></arg>
-      <arg><option>-c=<replaceable>file</replaceable></option></arg>
-      <group choice="req">
-         <arg>gencaches</arg>
-         <arg>showpkg <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
-         <arg>showsrc <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
-         <arg>stats</arg>
-         <arg>dump</arg>
-         <arg>dumpavail</arg>
-         <arg>unmet</arg>
-         <arg>search <arg choice="plain"><replaceable>regex</replaceable></arg></arg>
-         <arg>show <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
-         <arg>depends <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
-         <arg>rdepends <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
-         <arg>pkgnames <arg choice="plain"><replaceable>prefix</replaceable></arg></arg>
-         <arg>dotty <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
-         <arg>xvcg <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
-         <arg>policy <arg choice="plain" rep="repeat"><replaceable>pkgs</replaceable></arg></arg>
-         <arg>madison <arg choice="plain" rep="repeat"><replaceable>pkgs</replaceable></arg></arg>
-      </group>   
-   </cmdsynopsis>
- </refsynopsisdiv>
- 
+ &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 
diff --git a/doc/apt-cdrom.8.xml b/doc/apt-cdrom.8.xml
index 53ab392ab..94fc6fd8b 100644
--- a/doc/apt-cdrom.8.xml
+++ b/doc/apt-cdrom.8.xml
@@ -32,20 +32,7 @@
     <refpurpose>APT CDROM management utility</refpurpose>
  </refnamediv>
 
- <!-- Arguments -->
- <refsynopsisdiv>
-   <cmdsynopsis>
-      <command>apt-cdrom</command>
-      <arg><option>-hvrmfan</option></arg>
-      <arg><option>-d=<replaceable>cdrom mount point</replaceable></option></arg>
-      <arg><option>-o=<replaceable>config string</replaceable></option></arg>
-      <arg><option>-c=<replaceable>file</replaceable></option></arg>
-      <group>
-         <arg>add</arg>
-         <arg>ident</arg>
-      </group>   
-   </cmdsynopsis>
- </refsynopsisdiv>
+ &synopsis-command-apt-cdrom;
 
  <refsect1><title>Description</title>
    <para><command>apt-cdrom</command> is used to add a new CDROM to APTs list
diff --git a/doc/apt-config.8.xml b/doc/apt-config.8.xml
index 862a034a1..b6fcf4bf2 100644
--- a/doc/apt-config.8.xml
+++ b/doc/apt-config.8.xml
@@ -33,20 +33,8 @@
     <refpurpose>APT Configuration Query program</refpurpose>
  </refnamediv>
 
- <!-- Arguments -->
- <refsynopsisdiv>
-   <cmdsynopsis>
-      <command>apt-config</command>
-      <arg><option>-hv</option></arg>
-      <arg><option>-o=<replaceable>config string</replaceable></option></arg>
-      <arg><option>-c=<replaceable>file</replaceable></option></arg>
-      <group choice="req">
-         <arg>shell</arg>
-         <arg>dump</arg>
-      </group>   
-   </cmdsynopsis>
- </refsynopsisdiv>
- 
+ &synopsis-command-apt-config;
+
  <refsect1><title>Description</title>
    <para><command>apt-config</command> is an internal program used by various
    portions of the APT suite to provide consistent configurability. It accesses
diff --git a/doc/apt-extracttemplates.1.xml b/doc/apt-extracttemplates.1.xml
index af4cacfce..8f28f8c54 100644
--- a/doc/apt-extracttemplates.1.xml
+++ b/doc/apt-extracttemplates.1.xml
@@ -33,16 +33,8 @@
     <refpurpose>Utility to extract DebConf config and templates from Debian packages</refpurpose>
  </refnamediv>
 
- <!-- Arguments -->
- <refsynopsisdiv>
-   <cmdsynopsis>
-      <command>apt-extracttemplates</command>
-      <arg><option>-hv</option></arg>
-      <arg><option>-t=<replaceable>temporary directory</replaceable></option></arg>
-      <arg choice="plain" rep="repeat"><replaceable>file</replaceable></arg>
-   </cmdsynopsis>
- </refsynopsisdiv>
- 
+ &synopsis-command-apt-extracttemplates;
+
  <refsect1><title>Description</title>
    <para><command>apt-extracttemplates</command> will take one or more Debian package files
    as input and write out (to a temporary directory) all associated config
diff --git a/doc/apt-ftparchive.1.xml b/doc/apt-ftparchive.1.xml
index b08ebe80f..93b109af1 100644
--- a/doc/apt-ftparchive.1.xml
+++ b/doc/apt-ftparchive.1.xml
@@ -33,29 +33,8 @@
     <refpurpose>Utility to generate index files</refpurpose>
  </refnamediv>
 
- <!-- Arguments -->
- <refsynopsisdiv>
-   <cmdsynopsis>
-      <command>apt-ftparchive</command>
-      <arg><option>-hvdsq</option></arg>
-      <arg><option>--md5</option></arg>
-      <arg><option>--delink</option></arg>
-      <arg><option>--readonly</option></arg>
-      <arg><option>--contents</option></arg>
-      <arg><option>--arch <replaceable>architecture</replaceable></option></arg>
-      <arg><option>-o <replaceable>config</replaceable>=<replaceable>string</replaceable></option></arg>
-      <arg><option>-c=<replaceable>file</replaceable></option></arg>      
-      <group choice="req">
-         <arg>packages<arg choice="plain" rep="repeat"><replaceable>path</replaceable></arg><arg><replaceable>override</replaceable><arg><replaceable>pathprefix</replaceable></arg></arg></arg>
-         <arg>sources<arg choice="plain" rep="repeat"><replaceable>path</replaceable></arg><arg><replaceable>override</replaceable><arg><replaceable>pathprefix</replaceable></arg></arg></arg>
-         <arg>contents <arg choice="plain"><replaceable>path</replaceable></arg></arg>
-         <arg>release <arg choice="plain"><replaceable>path</replaceable></arg></arg>
-         <arg>generate <arg choice="plain"><replaceable>config-file</replaceable></arg> <arg choice="plain" rep="repeat"><replaceable>section</replaceable></arg></arg>
-         <arg>clean <arg choice="plain"><replaceable>config-file</replaceable></arg></arg>
-      </group>
-   </cmdsynopsis>
- </refsynopsisdiv>
- 
+ &synopsis-command-apt-ftparchive;
+
  <refsect1><title>Description</title>
    <para><command>apt-ftparchive</command> is the command line tool that generates the index 
    files that APT uses to access a distribution source. The index files should 
diff --git a/doc/apt-get.8.xml b/doc/apt-get.8.xml
index fd1cd2540..65929e733 100644
--- a/doc/apt-get.8.xml
+++ b/doc/apt-get.8.xml
@@ -33,91 +33,8 @@
     <refpurpose>APT package handling utility -- command-line interface</refpurpose>
  </refnamediv>
 
- <!-- Arguments -->
- <refsynopsisdiv>
-   <cmdsynopsis>
-      <command>apt-get</command>
-      <arg><option>-sqdyfmubV</option></arg>
-      <arg>
-	      <option>-o=
-			  <replaceable>config_string</replaceable>
-	      </option>
-      </arg>
-      <arg>
-	      <option>-c=
-		      <replaceable>config_file</replaceable>
-	      </option>
-      </arg>
-      <arg>
-		<option>-t=</option>
-		<arg choice='plain'>
-			<replaceable>target_release</replaceable>
-		</arg>
-      </arg>
-      <arg>
-		<option>-a=</option>
-		<arg choice='plain'>
-			<replaceable>default_architecture</replaceable>
-		</arg>
-      </arg>
-
-
-      <group choice="req">
-         <arg choice='plain'>update</arg>
-         <arg choice='plain'>upgrade</arg>
-         <arg choice='plain'>dselect-upgrade</arg>
-         <arg choice='plain'>dist-upgrade</arg>
-         <arg choice='plain'>install 
-			 <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable>
-				<arg>
-					<group choice='req'>
-						<arg choice='plain'>
-							=<replaceable>pkg_version_number</replaceable>
-						</arg>
-						<arg choice='plain'>
-							/<replaceable>target_release</replaceable>
-						</arg>
-					</group>
-				</arg>
-			 </arg>
-	     </arg>
-         <arg choice='plain'>remove <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
-         <arg choice='plain'>purge <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
-         <arg choice='plain'>source 
-			 <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable>
-				<arg>
-					<group choice='req'>
-						<arg choice='plain'>
-							=<replaceable>pkg_version_number</replaceable>
-						</arg>
-						<arg choice='plain'>
-							/<replaceable>target_release</replaceable>
-						</arg>
-					</group>
-				</arg>
-			 </arg>
-	     </arg>
-         <arg choice='plain'>build-dep <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
-         <arg choice='plain'>check</arg>
-         <arg choice='plain'>clean</arg>
-         <arg choice='plain'>autoclean</arg>
-         <arg choice='plain'>autoremove</arg>
-		 <arg choice='plain'>
-			 <group choice='req'>
-				<arg choice='plain'>-v</arg>
-				<arg choice='plain'>--version</arg>
-			 </group>
-		 </arg>
-		 <arg choice='plain'>
-			 <group choice='req'>
-				<arg choice='plain'>-h</arg>
-				<arg choice='plain'>--help</arg>
-			 </group>
-		 </arg>
-      </group>   
-   </cmdsynopsis>
- </refsynopsisdiv>
- 
+ &synopsis-command-apt-get;
+
  <refsect1><title>Description</title>
    <para><command>apt-get</command> is the command-line tool for handling packages, and may be 
    considered the user's "back-end" to other tools using the APT
@@ -247,7 +164,7 @@
      <listitem><para><literal>source</literal> causes <command>apt-get</command> to fetch source packages. APT 
      will examine the available packages to decide which source package to 
      fetch. It will then find and download into the current directory the 
-     newest available version of that source package while respect the
+     newest available version of that source package while respecting the
      default release, set with the option <literal>APT::Default-Release</literal>,
      the <option>-t</option> option or per package with the
      <literal>pkg/release</literal> syntax, if possible.</para>
diff --git a/doc/apt-key.8.xml b/doc/apt-key.8.xml
index cae2b00a0..3748b5e17 100644
--- a/doc/apt-key.8.xml
+++ b/doc/apt-key.8.xml
@@ -25,15 +25,7 @@
     <refpurpose>APT key management utility</refpurpose>
  </refnamediv>
 
- <!-- Arguments -->
- <refsynopsisdiv>
-   <cmdsynopsis>
-      <command>apt-key</command>
-      <arg><option>--keyring <replaceable>filename</replaceable></option></arg>
-      <arg><replaceable>command</replaceable></arg>
-      <arg rep="repeat"><option><replaceable>arguments</replaceable></option></arg>
-   </cmdsynopsis>
- </refsynopsisdiv>
+ &synopsis-command-apt-key;
 
  <refsect1><title>Description</title>
    <para>
@@ -45,19 +37,19 @@
 
 <refsect1><title>Commands</title>
    <variablelist>
-     <varlistentry><term>add <replaceable>filename</replaceable></term>
+     <varlistentry><term>add &synopsis-param-filename;</term>
      <listitem>
      <para>
 
        Add a new key to the list of trusted keys.  The key is read
-       from <replaceable>filename</replaceable>, or standard input if
-       <replaceable>filename</replaceable> is <literal>-</literal>.
+       from &synopsis-param-filename;, or standard input if
+       &synopsis-param-filename; is <literal>-</literal>.
      </para>
 
      </listitem>
      </varlistentry>
 
-     <varlistentry><term>del <replaceable>keyid</replaceable></term>
+     <varlistentry><term>del &synopsis-param-keyid;</term>
      <listitem>
      <para>
 
@@ -68,11 +60,11 @@
      </listitem>
      </varlistentry>
 
-     <varlistentry><term>export <replaceable>keyid</replaceable></term>
+     <varlistentry><term>export &synopsis-param-keyid;</term>
      <listitem>
      <para>
 
-        Output the key <replaceable>keyid</replaceable> to standard output.
+        Output the key &synopsis-param-keyid; to standard output.
 
      </para>
 
@@ -161,7 +153,7 @@
  <refsect1><title>Options</title>
 <para>Note that options need to be defined before the commands described in the previous section.</para>
    <variablelist>
-      <varlistentry><term>--keyring <replaceable>filename</replaceable></term>
+      <varlistentry><term>--keyring &synopsis-param-filename;</term>
       <listitem><para>With this option it is possible to specify a specific keyring
       file the command should operate on. The default is that a command is executed
       on the <filename>trusted.gpg</filename> file as well as on all parts in the
diff --git a/doc/apt-mark.8.xml b/doc/apt-mark.8.xml
index 01c8665dd..d62731124 100644
--- a/doc/apt-mark.8.xml
+++ b/doc/apt-mark.8.xml
@@ -33,26 +33,8 @@
     <refpurpose>mark/unmark a package as being automatically-installed</refpurpose>
  </refnamediv>
 
- <!-- Arguments -->
- <refsynopsisdiv>
-   <cmdsynopsis>
-	<command>apt-mark</command>
-	<arg><option>-hv</option></arg>
-	<arg><option>-f=<replaceable>FILENAME</replaceable></option></arg>
-	<group choice="plain">
-		<arg choice="plain">
-			<group choice="req">
-				<arg choice="plain">auto</arg>
-				<arg choice="plain">manual</arg>
-				<arg choice="plain">showauto</arg>
-				<arg choice="plain">showmanual</arg>
-			</group>
-			<arg choice="plain" rep="repeat"><replaceable>package</replaceable></arg>
-		</arg>
-	</group>
-   </cmdsynopsis>
- </refsynopsisdiv>
- 
+ &synopsis-command-apt-mark;
+
  <refsect1><title>Description</title>
    <para><command>apt-mark</command> will change whether a package has
    been marked as being automatically installed.
diff --git a/doc/apt-sortpkgs.1.xml b/doc/apt-sortpkgs.1.xml
index f2bd3c3ea..c1d1aa1e1 100644
--- a/doc/apt-sortpkgs.1.xml
+++ b/doc/apt-sortpkgs.1.xml
@@ -33,17 +33,8 @@
     <refpurpose>Utility to sort package index files</refpurpose>
  </refnamediv>
 
- <!-- Arguments -->
- <refsynopsisdiv>
-   <cmdsynopsis>
-      <command>apt-sortpkgs</command>
-      <arg><option>-hvs</option></arg>
-      <arg><option>-o=<replaceable>config string</replaceable></option></arg>
-      <arg><option>-c=<replaceable>file</replaceable></option></arg>
-      <arg choice="plain" rep="repeat"><replaceable>file</replaceable></arg>
-   </cmdsynopsis>
- </refsynopsisdiv>
- 
+ &synopsis-command-apt-sortpkgs;
+
  <refsect1><title>Description</title>
    <para><command>apt-sortpkgs</command> will take an index file (Source index or Package 
    index) and sort the records so that they are ordered by the package name. 
diff --git a/doc/apt-verbatim.ent b/doc/apt-verbatim.ent
index 14cd70e89..ad4554e2f 100644
--- a/doc/apt-verbatim.ent
+++ b/doc/apt-verbatim.ent
@@ -192,3 +192,158 @@
 <!ENTITY oldstable-codename "lenny">
 <!ENTITY stable-codename "squeeze">
 <!ENTITY testing-codename "wheezy">
+
+
+<!-- Arguments -->
+<!ENTITY synopsis-arg-option "<arg><option>-o=<replaceable>&synopsis-config-string;</replaceable></option></arg>">
+<!ENTITY synopsis-arg-config "<arg><option>-c=<filename><replaceable>&synopsis-config-file;</replaceable></filename></option></arg>">
+<!ENTITY synopsis-arg-target-release "<arg><option>-t=<replaceable>&synopsis-target-release;</replaceable></option></arg>">
+<!ENTITY synopsis-arg-architecture "<arg><option>-a=<replaceable>&synopsis-architecture;</replaceable></option></arg>">
+<!ENTITY synopsis-arg-pkgver "<arg choice='plain' rep='repeat'><replaceable>&synopsis-pkg;</replaceable><arg><group choice='req'>
+	<arg choice='plain'>=<replaceable>&synopsis-pkg-ver-number;</replaceable></arg>
+	<arg choice='plain'>/<replaceable>&synopsis-target-release;</replaceable></arg>
+</group></arg></arg>">
+<!ENTITY synopsis-arg-pkg "<arg choice='plain' rep='repeat'><replaceable>&synopsis-pkg;</replaceable></arg>">
+<!ENTITY synopsis-param-filename "<filename><replaceable>&synopsis-filename;</replaceable></filename>">
+<!ENTITY synopsis-help "<arg choice='plain'><group choice='req'><arg choice='plain'>-v</arg><arg choice='plain'>--version</arg></group></arg>
+	<arg choice='plain'><group choice='req'><arg choice='plain'>-h</arg><arg choice='plain'>--help</arg></group></arg>">
+<!ENTITY synopsis-command-apt-get "<refsynopsisdiv><cmdsynopsis>
+	<command>apt-get</command>
+	<arg><option>-asqdyfmubV</option></arg>
+	&synopsis-arg-option;
+	&synopsis-arg-config;
+	&synopsis-arg-target-release;
+	&synopsis-arg-architecture;
+	<group choice='req'>
+		<arg choice='plain'>update</arg>
+		<arg choice='plain'>upgrade</arg>
+		<arg choice='plain'>dselect-upgrade</arg>
+		<arg choice='plain'>dist-upgrade</arg>
+		<arg choice='plain'>install &synopsis-arg-pkgver;</arg>
+		<arg choice='plain'>remove &synopsis-arg-pkg;</arg>
+		<arg choice='plain'>purge &synopsis-arg-pkg;</arg>
+		<arg choice='plain'>source &synopsis-arg-pkgver;</arg>
+		<arg choice='plain'>build-dep &synopsis-arg-pkgver;</arg>
+		<arg choice='plain'>download &synopsis-arg-pkgver;</arg>
+		<arg choice='plain'>check</arg>
+		<arg choice='plain'>clean</arg>
+		<arg choice='plain'>autoclean</arg>
+		<arg choice='plain'>autoremove</arg>
+		&synopsis-help;
+	</group>
+</cmdsynopsis></refsynopsisdiv>">
+<!ENTITY synopsis-command-apt-cache "<refsynopsisdiv><cmdsynopsis>
+	<command>apt-cache</command>
+	<arg><option>-agipns</option></arg>
+	&synopsis-arg-option;
+	&synopsis-arg-config;
+	<group choice='req'>
+		<arg choice='plain'>gencaches</arg>
+		<arg choice='plain'>showpkg &synopsis-arg-pkg;</arg>
+		<arg choice='plain'>showsrc &synopsis-arg-pkg;</arg>
+		<arg choice='plain'>stats</arg>
+		<arg choice='plain'>dump</arg>
+		<arg choice='plain'>dumpavail</arg>
+		<arg choice='plain'>unmet</arg>
+		<arg choice='plain'>search <arg choice='plain' rep='repeat'><replaceable>&synopsis-regex;</replaceable></arg></arg>
+		<arg choice='plain'>show &synopsis-arg-pkgver;</arg>
+		<arg choice='plain'>depends &synopsis-arg-pkgver;</arg>
+		<arg choice='plain'>rdepends &synopsis-arg-pkgver;</arg>
+		<arg choice='plain'>pkgnames <arg choice='plain'><replaceable>&synopsis-prefix;</replaceable></arg></arg>
+		<arg choice='plain'>dotty &synopsis-arg-pkgver;</arg>
+		<arg choice='plain'>xvcg &synopsis-arg-pkgver;</arg>
+		<arg choice='plain'>policy &synopsis-arg-pkg;</arg>
+		<arg choice='plain'>madison &synopsis-arg-pkg;</arg>
+		&synopsis-help;
+	</group>
+</cmdsynopsis></refsynopsisdiv>">
+<!ENTITY synopsis-command-apt-cdrom "<refsynopsisdiv><cmdsynopsis>
+	<command>apt-cdrom</command>
+	<arg><option>-rmfan</option></arg>
+	<arg><option>-d=<replaceable>&synopsis-cdrom-mount;</replaceable></option></arg>
+	&synopsis-arg-option;
+	&synopsis-arg-config;
+	<group choice='req'>
+		<arg choice='plain'>add</arg>
+		<arg choice='plain'>ident</arg>
+		&synopsis-help;
+	</group>
+</cmdsynopsis></refsynopsisdiv>">
+<!ENTITY synopsis-command-apt-config "<refsynopsisdiv><cmdsynopsis>
+	<command>apt-config</command>
+	&synopsis-arg-option;
+	&synopsis-arg-config;
+	<group choice='req'>
+		<arg choice='plain'>shell</arg>
+		<arg choice='plain'>dump</arg>
+		&synopsis-help;
+	</group>
+</cmdsynopsis></refsynopsisdiv>">
+<!ENTITY synopsis-command-apt-extracttemplates "<refsynopsisdiv><cmdsynopsis>
+	<command>apt-extracttemplates</command>
+	<arg><option>-t=<replaceable>&synopsis-tmp-directory;</replaceable></option></arg>
+	<arg choice='plain' rep='repeat'>&synopsis-param-filename;</arg>
+	&synopsis-help;
+</cmdsynopsis></refsynopsisdiv>">
+<!ENTITY synopsis-arg-ftparchive "<arg choice='plain' rep='repeat'><replaceable>&synopsis-path;</replaceable></arg><arg><filename><replaceable>&synopsis-override;</replaceable></filename><arg><replaceable>&synopsis-pathprefix;</replaceable></arg></arg>">
+<!ENTITY synopsis-command-apt-ftparchive "<refsynopsisdiv><cmdsynopsis>
+	<command>apt-ftparchive</command>
+	<arg><option>-dsq</option></arg>
+	<arg><option>--md5</option></arg>
+	<arg><option>--delink</option></arg>
+	<arg><option>--readonly</option></arg>
+	<arg><option>--contents</option></arg>
+	<arg><option>--arch <replaceable>architecture</replaceable></option></arg>
+	&synopsis-arg-option;
+	&synopsis-arg-config;
+	<group choice='req'>
+		<arg choice='plain'>packages &synopsis-arg-ftparchive;</arg>
+		<arg choice='plain'>sources &synopsis-arg-ftparchive;</arg>
+		<arg choice='plain'>contents <arg choice='plain'><replaceable>&synopsis-path;</replaceable></arg></arg>
+		<arg choice='plain'>release <arg choice='plain'><replaceable>&synopsis-path;</replaceable></arg></arg>
+		<arg choice='plain'>generate <arg choice='plain'><replaceable>&synopsis-config-file;</replaceable></arg> <arg choice='plain' rep='repeat'><replaceable>&synopsis-section;</replaceable></arg></arg>
+		<arg choice='plain'>clean <arg choice='plain'><replaceable>&synopsis-config-file;</replaceable></arg></arg>
+		&synopsis-help;
+	</group>
+</cmdsynopsis></refsynopsisdiv>">
+<!ENTITY synopsis-param-keyid "<replaceable>&synopsis-keyid;</replaceable>">
+<!ENTITY synopsis-command-apt-key "<refsynopsisdiv><cmdsynopsis>
+	<command>apt-key</command>
+	<arg><option>--keyring &synopsis-param-filename;</option></arg>
+	<group choice='req'>
+		<arg choice='plain'>add &synopsis-param-filename;</arg>
+		<arg choice='plain'>del &synopsis-param-keyid;</arg>
+		<arg choice='plain'>export &synopsis-param-keyid;</arg>
+		<arg choice='plain'>exportall</arg>
+		<arg choice='plain'>list</arg>
+		<arg choice='plain'>finger</arg>
+		<arg choice='plain'>adv</arg>
+		<arg choice='plain'>update</arg>
+		<arg choice='plain'>net-update</arg>
+		&synopsis-help;
+	</group>
+</cmdsynopsis></refsynopsisdiv>">
+<!ENTITY synopsis-command-apt-mark "<refsynopsisdiv><cmdsynopsis>
+	<command>apt-mark</command>
+	<arg><option>-f=&synopsis-param-filename;</option></arg>
+	<group choice='plain'>
+		<arg choice='plain'>
+			<group choice='req'>
+				<arg choice='plain'>auto</arg>
+				<arg choice='plain'>manual</arg>
+				<arg choice='plain'>showauto</arg>
+				<arg choice='plain'>showmanual</arg>
+			</group>
+			&synopsis-arg-pkg;
+		</arg>
+		&synopsis-help;
+	</group>
+</cmdsynopsis></refsynopsisdiv>">
+<!ENTITY synopsis-command-apt-sortpkgs "<refsynopsisdiv><cmdsynopsis>
+	<command>apt-sortpkgs</command>
+	<arg><option>-s</option></arg>
+	&synopsis-arg-option;
+	&synopsis-arg-config;
+	<arg choice='plain' rep='repeat'>&synopsis-param-filename;</arg>
+	&synopsis-help;
+</cmdsynopsis></refsynopsisdiv>">
diff --git a/doc/apt.ent b/doc/apt.ent
index fc745989f..e48087fa7 100644
--- a/doc/apt.ent
+++ b/doc/apt.ent
@@ -208,3 +208,46 @@
      This is done on purpose, to avoid losing content when the
      translation is lagging behind the original content.
 ">
+
+<!-- TRANSLATOR: used as in -o=config_string  e.g. -o=Debug::pkgProblemResolver=1 -->
+<!ENTITY synopsis-config-string "config_string">
+
+<!-- TRANSLATOR: used as in -c=config_file  e.g. -c=./apt.conf -->
+<!ENTITY synopsis-config-file "config_file">
+
+<!-- TRANSLATOR: used as in -t=target_release or pkg/target_release  e.g. -t=squeeze apt/experimental -->
+<!ENTITY synopsis-target-release "target_release">
+
+<!-- TRANSLATOR: used as in -a=architecture  e.g. -a=armel -->
+<!ENTITY synopsis-architecture "architecture">
+
+<!-- TRANSLATOR: used as in apt-get install pkg  e.g. apt-get install awesome -->
+<!ENTITY synopsis-pkg "pkg">
+
+<!-- TRANSLATOR: used as in pkg=pkg_version_number  e.g. apt=0.8.15 -->
+<!ENTITY synopsis-pkg-ver-number "pkg_version_number">
+
+<!-- TRANSLATOR: used as in apt-cache pkgnames prefix  e.g. apt-cache pkgnames apt -->
+<!ENTITY synopsis-prefix "prefix">
+
+<!-- TRANSLATOR: used as in apt-cache search regex  e.g. apt-cache search awesome -->
+<!ENTITY synopsis-regex "regex">
+
+<!-- TRANSLATOR: used as in apt-cdrom -d=cdrom_mount_point  e.g. apt-cdrom -d=/media/cdrom -->
+<!ENTITY synopsis-cdrom-mount "cdrom_mount_point">
+
+<!-- TRANSLATOR: used as in apt-extracttemplates -t=temporary_directory  e.g. apt-extracttemplates -t=/tmp -->
+<!ENTITY synopsis-tmp-directory "temporary_directory">
+
+<!-- TRANSLATOR: used as in apt-extracttemplates filename -->
+<!ENTITY synopsis-filename "filename">
+
+<!-- TRANSLATOR: used as parameters for apt-ftparchive  e.g. apt-ftparchive packages path override pathprefix -->
+<!ENTITY synopsis-path "path">
+<!ENTITY synopsis-pathprefix "pathprefix">
+<!ENTITY synopsis-section "section">
+<!ENTITY synopsis-override "override">
+
+<!-- TRANSLATOR: used as in apt-key export keyid  e.g. apt-key export 473041FA -->
+<!ENTITY synopsis-keyid "keyid">
+
diff --git a/doc/makefile b/doc/makefile
index 4fcf3bd10..df2ddb25f 100644
--- a/doc/makefile
+++ b/doc/makefile
@@ -15,7 +15,7 @@ include $(DEBIANDOC_H)
 ifdef XSLTPROC
 # generate a list of accepted man page translations
 SOURCE = $(patsubst %.xml,%,$(wildcard *.?.xml))
-INCLUDES = apt.ent
+INCLUDES = apt.ent apt-verbatim.ent
 STYLESHEET=manpage-style.xsl
 
 LOCAL := manpage-$(firstword $(SOURCE))
@@ -67,26 +67,21 @@ veryclean-subdirs:
 		rm -rf $$dir; \
 	done
 
+.PHONY: update-po po4a stats
+
 ifdef PO4A
 doc: po4a
 
-clean: po4a-clean
-
-.PHONY: update-po po4a stats
 update-po:
 	po4a --previous --no-backups --force --no-translations po4a.conf
 
-po4a-clean:
-	po4a --previous --rm-backups --rm-translations po4a.conf
-
 po4a:
 	po4a --previous --no-backups po4a.conf
+endif
 
 stats:
 	for i in po/*.po; do echo -n "$$i: "; msgfmt --statistics $$i; done
 
-endif
-
 ifdef DOXYGEN
 DOXYGEN_SOURCES = $(shell find $(BASE)/apt-pkg -not -name .\\\#* -and \( -name \*.cc -or -name \*.h \) )
 
@@ -96,9 +91,6 @@ doxygen-clean:
 	rm -fr $(BUILD)/doc/doxygen
 	rm -f $(BUILD)/doc/doxygen-stamp
 
-$(BUILD)/doc/Doxyfile: Doxyfile.in
-	(cd $(BUILD) && ./config.status doc/Doxyfile)
-
 $(BUILD)/doc/doxygen-stamp: $(DOXYGEN_SOURCES) $(BUILD)/doc/Doxyfile
 	rm -fr $(BUILD)/doc/doxygen
 	mkdir $(BUILD)/doc/doxygen  # some versions seem to not create this directory #628799
diff --git a/doc/po/apt-doc.pot b/doc/po/apt-doc.pot
index 364dce12f..5cc0b53fe 100644
--- a/doc/po/apt-doc.pot
+++ b/doc/po/apt-doc.pot
@@ -2845,7 +2845,7 @@ msgid ""
 "<literal>source</literal> causes <command>apt-get</command> to fetch source "
 "packages. APT will examine the available packages to decide which source "
 "package to fetch. It will then find and download into the current directory "
-"the newest available version of that source package while respect the "
+"the newest available version of that source package while respecting the "
 "default release, set with the option "
 "<literal>APT::Default-Release</literal>, the <option>-t</option> option or "
 "per package with the <literal>pkg/release</literal> syntax, if possible."
diff --git a/doc/po/de.po b/doc/po/de.po
index 9a3415051..0db7a13fb 100644
--- a/doc/po/de.po
+++ b/doc/po/de.po
@@ -3768,7 +3768,7 @@ msgid ""
 "<literal>source</literal> causes <command>apt-get</command> to fetch source "
 "packages. APT will examine the available packages to decide which source "
 "package to fetch. It will then find and download into the current directory "
-"the newest available version of that source package while respect the "
+"the newest available version of that source package while respecting the "
 "default release, set with the option <literal>APT::Default-Release</"
 "literal>, the <option>-t</option> option or per package with the "
 "<literal>pkg/release</literal> syntax, if possible."
diff --git a/doc/po/es.po b/doc/po/es.po
index 35b8d0af7..645be1ab2 100644
--- a/doc/po/es.po
+++ b/doc/po/es.po
@@ -3820,7 +3820,7 @@ msgid ""
 "<literal>source</literal> causes <command>apt-get</command> to fetch source "
 "packages. APT will examine the available packages to decide which source "
 "package to fetch. It will then find and download into the current directory "
-"the newest available version of that source package while respect the "
+"the newest available version of that source package while respecting the "
 "default release, set with the option <literal>APT::Default-Release</"
 "literal>, the <option>-t</option> option or per package with the "
 "<literal>pkg/release</literal> syntax, if possible."
diff --git a/doc/po/fr.po b/doc/po/fr.po
index 2e0e766a7..6292cdcd5 100644
--- a/doc/po/fr.po
+++ b/doc/po/fr.po
@@ -465,7 +465,7 @@ msgstr ""
 "<!ENTITY file-preferences \"\n"
 "     <varlistentry><term><filename>/etc/apt/preferences</filename></term>\n"
 "     <listitem><para>Fichier des préférences.\n"
-"     C'est dans ce fichier qu'on peut faire de l'étiquetage (pinning) c'est-à-dire, choisir d'obtenir des paquets d'une source distincte ou d'une distribution différente.\n"
+"     C'est dans ce fichier qu'on peut faire de l'épinglage (pinning) c'est-à-dire, choisir d'obtenir des paquets d'une source distincte ou d'une distribution différente.\n"
 "     Élément de configuration : <literal>Dir::Etc::Preferences</literal>.</para></listitem>\n"
 "     </varlistentry>\n"
 
@@ -3752,7 +3752,7 @@ msgid ""
 "<literal>source</literal> causes <command>apt-get</command> to fetch source "
 "packages. APT will examine the available packages to decide which source "
 "package to fetch. It will then find and download into the current directory "
-"the newest available version of that source package while respect the "
+"the newest available version of that source package while respecting the "
 "default release, set with the option <literal>APT::Default-Release</"
 "literal>, the <option>-t</option> option or per package with the "
 "<literal>pkg/release</literal> syntax, if possible."
@@ -4444,7 +4444,7 @@ msgid ""
 "also the &apt-preferences; manual page."
 msgstr ""
 "Cette option contrôle l'entrée par défaut pour les questions de "
-"distribution ; une étiquette (pin) par défaut dont la priorité vaut 990 est "
+"distribution ; un épinglage (pin) par défaut dont la priorité vaut 990 est "
 "créée en utilisant la chaîne spécifiée. Le fichier des préférences peut "
 "annuler cette décision. En clair, cette option permet de contrôler "
 "simplement dans quelle distribution seront récupérés les paquets. Par "
diff --git a/doc/po/it.po b/doc/po/it.po
index 4571690e1..505553b55 100644
--- a/doc/po/it.po
+++ b/doc/po/it.po
@@ -2821,7 +2821,7 @@ msgid ""
 "<literal>source</literal> causes <command>apt-get</command> to fetch source "
 "packages. APT will examine the available packages to decide which source "
 "package to fetch. It will then find and download into the current directory "
-"the newest available version of that source package while respect the "
+"the newest available version of that source package while respecting the "
 "default release, set with the option <literal>APT::Default-Release</"
 "literal>, the <option>-t</option> option or per package with the "
 "<literal>pkg/release</literal> syntax, if possible."
diff --git a/doc/po/ja.po b/doc/po/ja.po
index 22488b227..368572943 100644
--- a/doc/po/ja.po
+++ b/doc/po/ja.po
@@ -3907,7 +3907,7 @@ msgid ""
 "<literal>source</literal> causes <command>apt-get</command> to fetch source "
 "packages. APT will examine the available packages to decide which source "
 "package to fetch. It will then find and download into the current directory "
-"the newest available version of that source package while respect the "
+"the newest available version of that source package while respecting the "
 "default release, set with the option <literal>APT::Default-Release</"
 "literal>, the <option>-t</option> option or per package with the "
 "<literal>pkg/release</literal> syntax, if possible."
diff --git a/doc/po/pl.po b/doc/po/pl.po
index 41eb56684..08c1b1660 100644
--- a/doc/po/pl.po
+++ b/doc/po/pl.po
@@ -3722,7 +3722,7 @@ msgid ""
 "<literal>source</literal> causes <command>apt-get</command> to fetch source "
 "packages. APT will examine the available packages to decide which source "
 "package to fetch. It will then find and download into the current directory "
-"the newest available version of that source package while respect the "
+"the newest available version of that source package while respecting the "
 "default release, set with the option <literal>APT::Default-Release</"
 "literal>, the <option>-t</option> option or per package with the "
 "<literal>pkg/release</literal> syntax, if possible."
diff --git a/doc/po/pt.po b/doc/po/pt.po
index e298281f8..e3d699bd0 100644
--- a/doc/po/pt.po
+++ b/doc/po/pt.po
@@ -3755,7 +3755,7 @@ msgid ""
 "<literal>source</literal> causes <command>apt-get</command> to fetch source "
 "packages. APT will examine the available packages to decide which source "
 "package to fetch. It will then find and download into the current directory "
-"the newest available version of that source package while respect the "
+"the newest available version of that source package while respecting the "
 "default release, set with the option <literal>APT::Default-Release</"
 "literal>, the <option>-t</option> option or per package with the "
 "<literal>pkg/release</literal> syntax, if possible."
diff --git a/doc/po/pt_BR.po b/doc/po/pt_BR.po
index 488350186..4f4c04caf 100644
--- a/doc/po/pt_BR.po
+++ b/doc/po/pt_BR.po
@@ -2878,7 +2878,7 @@ msgid ""
 "<literal>source</literal> causes <command>apt-get</command> to fetch source "
 "packages. APT will examine the available packages to decide which source "
 "package to fetch. It will then find and download into the current directory "
-"the newest available version of that source package while respect the "
+"the newest available version of that source package while respecting the "
 "default release, set with the option <literal>APT::Default-Release</"
 "literal>, the <option>-t</option> option or per package with the "
 "<literal>pkg/release</literal> syntax, if possible."