[Document -package-id, and use the term "package ID" consistently
Simon Marlow <marlowsd@gmail.com>**20090923094639
 Ignore-this: 234a5a2840b7a9608c9a5d4bc475080f
] {
hunk ./docs/users_guide/packages.xml 170
+      <varlistentry>
+        <term>
+	  <option>-package-id <replaceable>P</replaceable></option>
+	  <indexterm><primary><option>-package-id</option></primary></indexterm>
+	</term>
+	<listitem>
+          <para>
+            Exposes a package like <option>-package</option>, but the
+            package is named by its ID rather than by name.  This is a
+            more robust way to name packages, and can be used to
+            select packages that would otherwise be shadowed.  Cabal
+            passes <option>-package-id</option> flags to GHC.
+          </para>
+        </listitem>
+      </varlistentry>
+
hunk ./docs/users_guide/packages.xml 251
-            should be the full package identifier for the package,
-            that is it should include the version number.  For example:
+              should be the full
+              package <literal>name-version</literal> for the package.
+              For example:
hunk ./docs/users_guide/packages.xml 409
-  <sect2 id="broken-packages">
-    <title>Dependencies and broken packages</title>
+  <sect2 id="package-ids">
+    <title>Package IDs, dependencies, and broken packages</title>
hunk ./docs/users_guide/packages.xml 412
-    <para>Each installed package has a unique identifier, which
-      distinguishes it from all other installed packages on the
-      system.  To see the identifiers associated with each installed
-      package, use <literal>ghc-pkg list -v</literal>:</para>
+    <para>Each installed package has a unique identifier (the
+      &ldquo;installed package ID&rdquo;, or just &ldquo;package
+      ID&rdquo; for short) , which distinguishes it from all other
+      installed packages on the system.  To see the package IDs
+      associated with each installed package, use <literal>ghc-pkg
+      list -v</literal>:</para>
hunk ./docs/users_guide/packages.xml 431
-      The string in parentheses after the package name is the unique
-      identifier: it normally begins with the package name and
-      version, and ends in a hash string derived from the compiled
-      package.  Dependencies between packages are expressed in terms
-      of these unique identifiers, rather than just packages and
-      versions.  For example, take a look at the dependencies of
-      the <literal>haskell98</literal> package:
+      The string in parentheses after the package name is the package
+      ID: it normally begins with the package name and version, and
+      ends in a hash string derived from the compiled package.
+      Dependencies between packages are expressed in terms of package
+      IDs, rather than just packages and versions.  For example, take
+      a look at the dependencies of the <literal>haskell98</literal>
+      package:
hunk ./docs/users_guide/packages.xml 452
-      The purpose of the unique package identifier is to detect
-      problems caused by re-installing a package without also
-      recompiling the packages that depend on it.  Recompiling
-      dependencies is necessary, because the newly compiled package
-      may have a differnt ABI (Application Binary Interface) than the
-      previous version, even if both packages were built from the same
-      source code using the same compiler.  With unique package
-      identifiers, a recompiled package will have a different unique
-      identifer from the previous version, so packages that depended
-      on the previous version are now orphaned - one of their
-      dependencies is not satisfied.  Packages that are broken in this
-      way are shown in the <literal>ghc-pkg list</literal> output
-      either in red (if possible) or otherwise surrounded by
-      braces.  In the following example, we have recompiled and
-      reinstalled the <literal>filepath</literal> package, and this
-      has caused various dependencies
-      including <literal>Cabal</literal> to break:</para>
+      The purpose of the package ID is to detect problems caused by
+      re-installing a package without also recompiling the packages
+      that depend on it.  Recompiling dependencies is necessary,
+      because the newly compiled package may have a differnt ABI
+      (Application Binary Interface) than the previous version, even
+      if both packages were built from the same source code using the
+      same compiler.  With package IDs, a recompiled
+      package will have a different package ID from the previous
+      version, so packages that depended on the previous version are
+      now orphaned - one of their dependencies is not satisfied.
+      Packages that are broken in this way are shown in
+      the <literal>ghc-pkg list</literal> output either in red (if
+      possible) or otherwise surrounded by braces.  In the following
+      example, we have recompiled and reinstalled
+      the <literal>filepath</literal> package, and this has caused
+      various dependencies including <literal>Cabal</literal> to
+      break:</para>
hunk ./docs/users_guide/packages.xml 1159
-	  <para>The package's unique identifier.  It is up to you to
-	  choose a suitable one.</para>
+	  <para>The package ID.  It is up to you to choose a suitable
+	  one.</para>
}