clarify the note for the pkgnames command in the manpage (Closes: #547599)

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

diff --git a/doc/apt-cache.8.xml b/doc/apt-cache.8.xml
index 789c3d22874c1f94b71b2b6b2d63a3330f408932..9851135b147b85e0c1caabed46d52ca8481c75e9 100644 (file)
--- a/doc/apt-cache.8.xml
+++ b/doc/apt-cache.8.xml
@@ -21,6 +21,7 @@
  <refmeta>
    <refentrytitle>apt-cache</refentrytitle>
    <manvolnum>8</manvolnum>
  <refmeta>
    <refentrytitle>apt-cache</refentrytitle>
    <manvolnum>8</manvolnum>

+   <refmiscinfo class="manual">APT</refmiscinfo>

  </refmeta>
  
  <!-- Man page title -->
  </refmeta>
  
  <!-- Man page title -->


@@ -51,6 +52,7 @@
          <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>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>   
          <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>   


@@ -151,7 +153,7 @@ Reverse Provides:
        a dependency but were not provided by any package. Missing packages may 
        be in evidence if a full distribution is not accessed, or if a package
        (real or virtual) has been dropped from the distribution. Usually they
        a dependency but were not provided by any package. Missing packages may 
        be in evidence if a full distribution is not accessed, or if a package
        (real or virtual) has been dropped from the distribution. Usually they

-       are referenced from Conflicts statements.</para>
+       are referenced from Conflicts or Breaks statements.</para>

        </listitem>
 
        <listitem><para><literal>Total distinct</literal> versions is the number of package versions 
        </listitem>
 
        <listitem><para><literal>Total distinct</literal> versions is the number of package versions 


@@ -197,9 +199,14 @@ Reverse Provides:
 
      <varlistentry><term>search <replaceable>regex [ regex ... ]</replaceable></term>
      <listitem><para><literal>search</literal> performs a full text search on all available package
 
      <varlistentry><term>search <replaceable>regex [ regex ... ]</replaceable></term>
      <listitem><para><literal>search</literal> performs a full text search on all available package

-     lists for the regex pattern given. It searches the package names and the
+     lists for the POSIX regex pattern given, see 
+     <citerefentry><refentrytitle><command>regex</command></refentrytitle>
+     <manvolnum>7</manvolnum></citerefentry>.
+     It searches the package names and the

      descriptions for an occurrence of the regular expression and prints out
      descriptions for an occurrence of the regular expression and prints out

-     the package name and the short description. If <option>--full</option> is given
+     the package name and the short description, including virtual package
+     names.
+     If <option>--full</option> is given

      then output identical to <literal>show</literal> is produced for each matched
      package, and if <option>--names-only</option> is given then the long description
      is not searched, only the package name is.</para>
      then output identical to <literal>show</literal> is produced for each matched
      package, and if <option>--names-only</option> is given then the long description
      is not searched, only the package name is.</para>


@@ -219,11 +226,14 @@ Reverse Provides:
      </varlistentry>
 
      <varlistentry><term>pkgnames <replaceable>[ prefix ]</replaceable></term>
      </varlistentry>
 
      <varlistentry><term>pkgnames <replaceable>[ prefix ]</replaceable></term>

-     <listitem><para>This command prints the name of each package in the system. The optional
+     <listitem><para>This command prints the name of each package APT knows. The optional

      argument is a prefix match to filter the name list. The output is suitable
      for use in a shell tab complete function and the output is generated 
      extremely quickly. This command is best used with the 
      argument is a prefix match to filter the name list. The output is suitable
      for use in a shell tab complete function and the output is generated 
      extremely quickly. This command is best used with the 

-     <option>--generate</option> option.</para></listitem>
+     <option>--generate</option> option.</para>
+     <para>Note that a package which APT knows of is not nessasarily available to download,
+     installable or installed, e.g. virtual packages are also listed in the generated list.
+     </para></listitem>

      </varlistentry>
      
      <varlistentry><term>dotty <replaceable>pkg(s)</replaceable></term>
      </varlistentry>
      
      <varlistentry><term>dotty <replaceable>pkg(s)</replaceable></term>


@@ -244,6 +254,11 @@ Reverse Provides:
      <para>Caution, dotty cannot graph larger sets of packages.</para></listitem>
      </varlistentry>
      
      <para>Caution, dotty cannot graph larger sets of packages.</para></listitem>
      </varlistentry>
      

+     <varlistentry><term>xvcg <replaceable>pkg(s)</replaceable></term>
+        <listitem><para>The same as <literal>dotty</literal>, only for xvcg from the
+        <ulink url="http://rw4.cs.uni-sb.de/users/sander/html/gsvcg1.html">VCG tool</ulink>.
+        </para></listitem></varlistentry>
+

      <varlistentry><term>policy <replaceable>[ pkg(s) ]</replaceable></term>
      <listitem><para><literal>policy</literal> is meant to help debug issues relating to the 
      preferences file. With no arguments it will print out the 
      <varlistentry><term>policy <replaceable>[ pkg(s) ]</replaceable></term>
      <listitem><para><literal>policy</literal> is meant to help debug issues relating to the 
      preferences file. With no arguments it will print out the 


@@ -277,7 +292,7 @@ Reverse Provides:
      <listitem><para>Select the file to store the source cache. The source is used only by
      <literal>gencaches</literal> and it stores a parsed version of the package 
      information from remote sources. When building the package cache the 
      <listitem><para>Select the file to store the source cache. The source is used only by
      <literal>gencaches</literal> and it stores a parsed version of the package 
      information from remote sources. When building the package cache the 

-     source cache is used to advoid reparsing all of the package files.
+     source cache is used to avoid reparsing all of the package files.

      Configuration Item: <literal>Dir::Cache::srcpkgcache</literal>.</para></listitem>
      </varlistentry>
 
      Configuration Item: <literal>Dir::Cache::srcpkgcache</literal>.</para></listitem>
      </varlistentry>
 


@@ -289,7 +304,7 @@ Reverse Provides:
      </varlistentry>
 
      <varlistentry><term><option>-i</option></term><term><option>--important</option></term>
      </varlistentry>
 
      <varlistentry><term><option>-i</option></term><term><option>--important</option></term>

-     <listitem><para>Print only important dependencies; for use with unmet. Causes only Depends and 
+     <listitem><para>Print only important dependencies; for use with unmet and depends. Causes only Depends and 

      Pre-Depends relations to be printed.
      Configuration Item: <literal>APT::Cache::Important</literal>.</para></listitem>
      </varlistentry>
      Pre-Depends relations to be printed.
      Configuration Item: <literal>APT::Cache::Important</literal>.</para></listitem>
      </varlistentry>


@@ -345,21 +360,8 @@ Reverse Provides:
 
  <refsect1><title>Files</title>
    <variablelist>
 
  <refsect1><title>Files</title>
    <variablelist>

-     <varlistentry><term><filename>/etc/apt/sources.list</filename></term>
-     <listitem><para>Locations to fetch packages from.
-     Configuration Item: <literal>Dir::Etc::SourceList</literal>.</para></listitem>
-     </varlistentry>
-     
-     <varlistentry><term><filename>&statedir;/lists/</filename></term>
-     <listitem><para>Storage area for state information for each package resource specified in
-     &sources-list;
-     Configuration Item: <literal>Dir::State::Lists</literal>.</para></listitem>
-     </varlistentry>
-  
-     <varlistentry><term><filename>&statedir;/lists/partial/</filename></term>
-     <listitem><para>Storage area for state information in transit.
-     Configuration Item: <literal>Dir::State::Lists</literal> (implicit partial).</para></listitem>
-     </varlistentry>     
+     &file-sourceslist;
+     &file-statelists;

    </variablelist>
  </refsect1>
 
    </variablelist>
  </refsect1>