From 4d57e7cf24bbac760d95fabc93a8eaffb2e1548e Mon Sep 17 00:00:00 2001
From: Sean Gillies <sean@mapbox.com>
Date: Thu, 14 Feb 2019 19:44:51 -0700
Subject: [PATCH] Add an FAQ

---
 docs/faq.rst   | 34 ++++++++++++++++++++++++++++++++++
 docs/index.rst |  1 +
 2 files changed, 35 insertions(+)
 create mode 100644 docs/faq.rst

diff --git a/docs/faq.rst b/docs/faq.rst
new file mode 100644
index 00000000..8fbe4704
--- /dev/null
+++ b/docs/faq.rst
@@ -0,0 +1,34 @@
+Frequently Asked Questions
+==========================
+
+Where is "ERROR 4: Unable to open EPSG support file gcs.csv" coming from and what does it mean?
+-----------------------------------------------------------------------------------------------
+
+The full message is "ERROR 4: Unable to open EPSG support file gcs.csv.  Try
+setting the GDAL_DATA environment variable to point to the directory containing
+EPSG csv files." The GDAL/OGR library prints this text to your process's stdout
+stream when it can not find the gcs.csv data file it needs to interpret spatial
+reference system information stored with a dataset. If you've never seen this
+before, you can summon this message by setting GDAL_DATA to a bogus value in
+your shell and running a command like ogrinfo:
+
+```bash
+$ GDAL_DATA="/lol/wut" ogrinfo example.shp -so example
+INFO: Open of 'example.shp'
+      using driver 'ESRI Shapefile' successful.
+
+Layer name: example
+Geometry: Polygon
+Feature Count: 67
+Extent: (-113.564247, 37.068981) - (-104.970871, 41.996277)
+ERROR 4: Unable to open EPSG support file gcs.csv.  Try setting the GDAL_DATA environment variable to point to the directory containing EPSG csv files.
+```
+
+If you're using GDAL software acquired by a package management system like apt
+or yum, or Homebrew, you can likely eliminate this message and the condition
+that causes it by unsetting GDAL_DATA in your environment.
+
+If you see this error message when using Rasterio in a Python program or when
+using Rasterio's CLI in a shell script, the solution is to upgrade to version
+1.0.18, which almost always sets GDAL_DATA when needed and otherwise leaves it
+alone.
diff --git a/docs/index.rst b/docs/index.rst
index 5ee3fbf8..0a87c1dc 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -51,6 +51,7 @@ Rasterio supports Python versions 2.7 and 3.3 or higher.
    topics/index
    api/index
    contributing
+   faq
 
 Indices and Tables
 ==================