support setting empty values (sanely) & removing support for

[apt.git] / doc / apt-mark.8.xml

diff --git a/doc/apt-mark.8.xml b/doc/apt-mark.8.xml
index 8f289c49a2f9eae141c9befe6dd001fc8e131e50..8dd157a60f00991a52958f0928fe65c7e0ec579c 100644 (file)
--- a/doc/apt-mark.8.xml
+++ b/doc/apt-mark.8.xml
@@ -1,13 +1,9 @@
 <?xml version="1.0" encoding="utf-8" standalone="no"?>
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
 <?xml version="1.0" encoding="utf-8" standalone="no"?>
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [

-
-<!ENTITY % aptent SYSTEM "apt.ent">
-%aptent;
-
-<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent">
-%aptverbatiment;
-
+<!ENTITY % aptent SYSTEM "apt.ent"> %aptent;
+<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment;
+<!ENTITY % aptvendor SYSTEM "apt-vendor.ent"> %aptvendor;

 ]>
 
 <refentry>
 ]>
 
 <refentry>


@@ -18,7 +14,7 @@
    &apt-email;
    &apt-product;
    <!-- The last update date -->
    &apt-email;
    &apt-product;
    <!-- The last update date -->

-   <date>2011-04-21T00:00:00Z</date>
+   <date>2015-09-25T00:00:00Z</date>

  </refentryinfo>
  
  <refmeta>
  </refentryinfo>
  
  <refmeta>


@@ -30,31 +26,37 @@
  <!-- Man page title -->
  <refnamediv>
     <refname>apt-mark</refname>
  <!-- Man page title -->
  <refnamediv>
     <refname>apt-mark</refname>

-    <refpurpose>mark/unmark a package as being automatically-installed</refpurpose>
+    <refpurpose>show, set and unset various settings for a package</refpurpose>

  </refnamediv>
 
  &synopsis-command-apt-mark;
 
  <refsect1><title>Description</title>
  </refnamediv>
 
  &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.
+    <para><command>apt-mark</command> can be used as a unified frontend to set
+       various settings for a package like marking a package as being
+       automatically/manually installed or changing <command>dpkg</command>
+       selections such as hold, install, deinstall and purge which are respected
+       e.g. by <command>apt-get dselect-upgrade</command> or <command>aptitude</command>.

    </para>
    </para>

+ </refsect1><refsect1><title>Automatically and manually installed packages</title>

    <para>
      When you request that a package is installed, and as a result
      other packages are installed to satisfy its dependencies, the
    <para>
      When you request that a package is installed, and as a result
      other packages are installed to satisfy its dependencies, the

-     dependencies are marked as being automatically installed.  Once
-     these automatically installed packages are no longer depended on
-     by any manually installed packages, they will be removed by e.g.
-     <command>apt-get</command> or <command>aptitude</command>.
+     dependencies are marked as being automatically installed, while
+     package you installed explicitely is marked as manually installed.
+     Once a automatically installed package is no longer depended on
+     by any manually installed package it is considered no longer needed
+     and e.g. <command>apt-get</command> or <command>aptitude</command>
+     will at least suggest removing them.

    </para>
    </para>

-     <variablelist>
+   <variablelist>

      <varlistentry><term><option>auto</option></term>
         <listitem><para><literal>auto</literal> is used to mark a
      package as being automatically installed, which will cause the
      package to be removed when no more manually installed packages
      depend on this package.
        </para></listitem>
      <varlistentry><term><option>auto</option></term>
         <listitem><para><literal>auto</literal> is used to mark a
      package as being automatically installed, which will cause the
      package to be removed when no more manually installed packages
      depend on this package.
        </para></listitem>

-       </varlistentry>
+     </varlistentry>

 
      <varlistentry><term><option>manual</option></term>
         <listitem><para><literal>manual</literal> is used to mark a
 
      <varlistentry><term><option>manual</option></term>
         <listitem><para><literal>manual</literal> is used to mark a


@@ -62,23 +64,7 @@
      package from being automatically removed if no other packages
      depend on it.
        </para></listitem>
      package from being automatically removed if no other packages
      depend on it.
        </para></listitem>

-       </varlistentry>
-
-       <varlistentry><term><option>hold</option></term>
-        <listitem><para><literal>hold</literal> is used to mark a
-       package as hold back, which will prevent the package from being
-       automatically installed, upgraded or removed.
-       The command is only a wrapper around <command>dpkg --set-selections</command>
-       and the state is therefore maintained by &dpkg; and not effected
-       by the <option>--filename</option> option.
-       </para></listitem>
-       </varlistentry>
-
-       <varlistentry><term><option>unhold</option></term>
-        <listitem><para><literal>unhold</literal> is used to cancel a
-       previously set hold on a package to allow all actions again.
-       </para></listitem>
-       </varlistentry>
+     </varlistentry>

 
        <varlistentry><term><option>showauto</option></term>
         <listitem><para><literal>showauto</literal> is used to print a
 
        <varlistentry><term><option>showauto</option></term>
         <listitem><para><literal>showauto</literal> is used to print a


@@ -86,38 +72,66 @@
      All automatically installed packages will be listed if no package is given.
      If packages are given only those which are automatically installed will be shown.
        </para></listitem>
      All automatically installed packages will be listed if no package is given.
      If packages are given only those which are automatically installed will be shown.
        </para></listitem>

-       </varlistentry>
+     </varlistentry>

 
        <varlistentry><term><option>showmanual</option></term>
         <listitem><para><literal>showmanual</literal> can be used in
      the same way as <literal>showauto</literal> except that it will print
      a list of manually installed packages instead.
        </para></listitem>
 
        <varlistentry><term><option>showmanual</option></term>
         <listitem><para><literal>showmanual</literal> can be used in
      the same way as <literal>showauto</literal> except that it will print
      a list of manually installed packages instead.
        </para></listitem>

+     </varlistentry>
+   </variablelist>
+
+   <refsect2><title>Options</title>
+     <variablelist>
+       <varlistentry>
+        <term><option>-f=&synopsis-param-filename;</option></term>
+        <term><option>--file=&synopsis-param-filename;</option></term>
+        <listitem><para>
+          Read/Write package stats from the filename given with the parameter
+          &synopsis-param-filename; instead of from the default location, which
+          is <filename>extended_status</filename> in the directory defined
+          by the Configuration Item: <literal>Dir::State</literal>.
+        </para></listitem>

        </varlistentry>
        </varlistentry>

+     </variablelist>
+   </refsect2>

 
 

-       <varlistentry><term><option>showhold</option></term>
-        <listitem><para><literal>showhold</literal> is used to print a list
-     of packages on hold in the same way as for the other show commands.
+ </refsect1><refsect1><title>Prevent changes for a package</title>
+   <variablelist>
+     <varlistentry><term><option>hold</option></term>
+        <listitem><para><literal>hold</literal> is used to mark a
+     package as held back, which will prevent the package from being
+     automatically installed, upgraded or removed.

        </para></listitem>
        </para></listitem>

-       </varlistentry>
+     </varlistentry>

 
 

+     <varlistentry><term><option>unhold</option></term>
+        <listitem><para><literal>unhold</literal> is used to cancel a
+     previously set hold on a package to allow all actions again.
+       </para></listitem>
+     </varlistentry>

 
 

-     </variablelist>
- </refsect1>
- 
- <refsect1><title>options</title>
-   
-   <variablelist>
-       <varlistentry>
-          <term><option>-f=&synopsis-param-filename;</option></term>
-          <term><option>--file=&synopsis-param-filename;</option></term>
-     <listitem><para>
-     Read/Write package stats from the filename given with the parameter
-     &synopsis-param-filename; instead of from the default location, which
-     is <filename>extended_status</filename> in the directory defined
-     by the Configuration Item: <literal>Dir::State</literal>.</para></listitem>
+     <varlistentry><term><option>showhold</option></term>
+        <listitem><para><literal>showhold</literal> is used to print a list
+     of packages on hold in the same way as for the other show commands.
+       </para></listitem>

      </varlistentry>
      </varlistentry>

+   </variablelist>
+ </refsect1><refsect1><title>Shedule packages for install, remove and purge</title>
+ <para>
+    Some frontends like <command>apt-get dselect-upgrade</command> can be used to
+    apply previously sheduled changes to the install state of packages. Such changes
+    can be sheduled with the <option>install</option>, <option>remove</option>
+    (also known as <option>deinstall</option>) and <option>purge</option> commands.
+    Packages with a specific selection can be displayed with <option>showinstall</option>,
+    <option>showremove</option> and <option>showpurge</option> respectively.
+    More information about these so called dpkg selections can be found in &dpkg;.
+ </para>
+ </refsect1>

 
 

+ <refsect1><title>Options</title>
+   <variablelist>

      &apt-commonoptions;
    </variablelist>
  </refsect1>
      &apt-commonoptions;
    </variablelist>
  </refsect1>