diff --git a/Cabal/Distribution/Simple/Build/PathsModule.hs b/Cabal/Distribution/Simple/Build/PathsModule.hs
index 3149eecb64e7452dd57c29046802394890605826..e190f7a5c93c6cb690f28d5d48dfbf83eff85ebe 100644
--- a/Cabal/Distribution/Simple/Build/PathsModule.hs
+++ b/Cabal/Distribution/Simple/Build/PathsModule.hs
@@ -242,6 +242,9 @@ generate pkg_descr lbi clbi =
 
 -- | Generates the name of the environment variable controlling the path
 -- component of interest.
+--
+-- Note: The format of these strings is part of Cabal's public API;
+-- changing this function constitutes a *backwards-compatibility* break.
 pkgPathEnvVar :: PackageDescription
               -> String     -- ^ path component; one of \"bindir\", \"libdir\",
                             -- \"datadir\", \"libexecdir\", or \"sysconfdir\"
diff --git a/Cabal/doc/developing-packages.markdown b/Cabal/doc/developing-packages.markdown
index 64cc60dadfb8ef9a31074c2f467a92c89eaf5a29..806ce2cb72cf7582ca35ff04e086066862651ee5 100644
--- a/Cabal/doc/developing-packages.markdown
+++ b/Cabal/doc/developing-packages.markdown
@@ -2071,6 +2071,15 @@ getLibexecDir :: IO FilePath
 getSysconfDir :: IO FilePath
 ~~~~~~~~~~~~~~~
 
+The actual location of all these directories can be individually
+overridden at runtime using environment variables of the form
+`pkg_name_var`, where `pkg_name` is the name of the package with
+all hyphens converted into underscores, and `var` is either
+`bindir`, `libdir`, `datadir`, `libexedir` or `sysconfdir`.
+For example, the configured data directory for `pretty-show`
+is controlled with the `pretty_show_datadir` environment variable.
+
+
 ### Accessing the package version ###
 
 The aforementioned auto generated `Paths_`_pkgname_ module also