Update package description

2 files changed, 36 insertions, 47 deletions

diff --git a/README.md b/README.md
index d09b640..c14d645 100644
--- a/README.md
+++ b/README.md
@@ -1,29 +1,24 @@
 # cabal-helper
 
-`cabal-helper` provides a library which wraps the internal use of
-anexecutable to lift the restrictions imposed by linking against versions of
-GHC before `7.10`. This has the pleasant side effect of isolating the user
-from having to deal with Cabal version changes manually as `cabal-helper`
-can simply recompile it's helper program automatically as needed.
-
-`cabal-helper` uses a wrapper executable to compile the actual cabal-helper
-executable at runtime while linking against an arbitrary version of
-Cabal. This runtime-compiled helper executable is then used to extract
-various bits and peices from Cabal's on disk state (dist/setup-config)
-written by it's configure command.
-
-In addition to this the wrapper executable also supports installing any
-version of Cabal from hackage in case it cannot be found in any available
-package database. The wrapper installs these instances of the Cabal library
-into a private package database so as to not interfere with the user's
-packages.
-
-Furthermore the wrapper supports one special case namely reading a state
-file for Cabal itself. This is needed as Cabal compiles it's Setup.hs using
-itself and not using any version of Cabal installed in any package database.
-
-`cabal-helper` can compile with `Cabal >= 1.14` but requires `Cabal >= 1.16`
-at runtime.
+Cabal's little helper provides access to build information gathered by `cabal`
+when configuring a project. Specifically we're interested in retrieving enough
+information to bring up a compiler session, using the GHC API, which is similar
+to running `cabal repl` in a project.
+
+While simple in principle this is complicated by the fact that the information
+Cabal writes to disk is in an unstable format and only really accessible through
+the Cabal API itself.
+
+Since we do not want to bind the user of a development tool which utilises this
+library to a specific version of Cabal we compile the code which interfaces with
+the Cabal library's API on the user's machine, at runtime, against whichever
+version of Cabal was used to write the on disk information for a given project.
+
+If this version of Cabal is not available on the users machine anymore, which is
+fairly likely since cabal-install is usually linked statically, we have support
+for compiling the Cabal library also. In this case the library is installed into
+a private, isolated, package database in `$XDG_CACHE_DIR/cabal-helper` so as to
+not interfere with the user's package database.
 
 ## IRC
 
diff --git a/cabal-helper.cabal b/cabal-helper.cabal
index a205290..145a545 100644
--- a/cabal-helper.cabal
+++ b/cabal-helper.cabal
@@ -1,32 +1,26 @@
 name:                cabal-helper
 version:             0.8.0.0
-synopsis:            Simple interface to some of Cabal's configuration state used by ghc-mod
+synopsis:            Simple interface to some of Cabal's configuration state, mainly used by ghc-mod
 description:
-    @cabal-helper@ provides a library which wraps the internal use of an
-    executable to lift the restrictions imposed by linking against versions of
-    GHC before @7.10@. This has the pleasant side effect of isolating the user
-    from having to deal with Cabal version changes manually as @cabal-helper@
-    can simply recompile it's helper program automatically as needed.
+    Cabal's little helper provides access to build information gathered by @cabal@
+    when configuring a project. Specifically we're interested in retrieving enough
+    information to bring up a compiler session, using the GHC API, which is similar
+    to running @cabal repl@ in a project.
     .
-    @cabal-helper@ uses a wrapper executable to compile the actual cabal-helper
-    executable at runtime while linking against an arbitrary version of
-    Cabal. This runtime-compiled helper executable is then used to extract
-    various bits and peices from Cabal\'s on disk state (dist/setup-config)
-    written by it's configure command.
+    While simple in principle this is complicated by the fact that the information
+    Cabal writes to disk is in an unstable format and only really accessible through
+    the Cabal API itself.
     .
-    In addition to this the wrapper executable also supports installing any
-    version of Cabal from hackage in case it cannot be found in any available
-    package database. The wrapper installs these instances of the Cabal library
-    into a private package database so as to not interfere with the user's
-    packages.
+    Since we do not want to bind the user of a development tool which utilises this
+    library to a specific version of Cabal we compile the code which interfaces with
+    the Cabal library's API on the user's machine, at runtime, against whichever
+    version of Cabal was used to write the on disk information for a given project.
     .
-    Furthermore the wrapper supports one special case namely reading a state
-    file for Cabal itself. This is needed as Cabal compiles it's Setup.hs using
-    itself and not using any version of Cabal installed in any package database.
-    .
-    @cabal-helper@ can compile with @Cabal >= 1.14@ but requires @Cabal >= 1.16@
-    at runtime.
-
+    If this version of Cabal is not available on the users machine anymore, which is
+    fairly likely since cabal-install is usually linked statically, we have support
+    for compiling the Cabal library also. In this case the library is installed into
+    a private, isolated, package database in @$XDG_CACHE_DIR/cabal-helper@ so as to
+    not interfere with the user's package database.
 license:             AGPL-3
 license-file:        LICENSE
 license-files:       LICENSE LICENSE.cabal-dependency-licenses