- <para>Commands which only inspect the database (<literal>list</literal>,
- <literal>describe</literal>, <literal>field</literal>) will take into
- account the user's local package database too, unless the
- <literal>--global</literal> option is given. This matches the behaviour
- of GHC, which automatically reads the user's local database if it is
- available.</para>
+ <para>To see what package databases are in use, say
+ <literal>ghc-pkg list</literal>. The stack of databases that
+ <literal>ghc-pkg</literal> knows about can be modified using the
+ <literal>GHC_PACKAGE_PATH</literal> environment variable (see <xref
+ linkend="ghc-package-path" />, and using
+ <literal>--package-conf</literal> options on the
+ <literal>ghc-pkg</literal> command line.</para>
+
+ <para>When asked to modify a database, <literal>ghc-pkg</literal> modifies
+ the global database by default. Specifying <option>--user</option>
+ causes it to act on the user database, or <option>--package-conf</option>
+ can be used to act on another database entirely. When multiple of these
+ options are given, the rightmost one is used as the database to act
+ upon.</para>
+
+ <para>If the environment variable <literal>GHC_PACKAGE_PATH</literal> is
+ set, and its value does not end in a separator (<literal>:</literal> on
+ Unix, <literal>;</literal> on Windows), then the last database is
+ considered to be the global database, and will be modified by default by
+ <literal>ghc-pkg</literal>. The intention here is that
+ <literal>GHC_PACKAGE_PATH</literal> can be used to create a virtual
+ package environment into which Cabal packages can be installed without
+ setting anything other than <literal>GHC_PACKAGE_PATH</literal>.</para>