Improved documentation for Linux installation problems.

2 files changed, 22 insertions, 11 deletions

diff --git a/doc/manual/12_Compiling.md b/doc/manual/12_Compiling.md
index 2f6e19ea..a5ad4ed0 100644
--- a/doc/manual/12_Compiling.md
+++ b/doc/manual/12_Compiling.md
@@ -2,18 +2,19 @@
 
 ## Requirements
 
-Unfortunately, the requirements for building Textadept are not as minimal as
-running it.
+Unfortunately, the requirements for building Textadept are not quite as minimal
+as running it.
 
 #### Linux and BSD
 
 Linux systems need the GTK+ development libraries. Your package manager should
-allow you to install them. For Debian-based distributions, the package is
-typically called `libgtk2.0-dev`. Otherwise, compile and install it from the
-[GTK+ website](http://www.gtk.org/download-linux.html). Additionally you will
-need the [GNU C compiler](http://gcc.gnu.org) (`gcc`) and
+allow you to install them. For Debian-based distributions like Ubuntu, the
+package is typically called `libgtk2.0-dev`. Otherwise, compile and install GTK
+from the [GTK+ website](http://www.gtk.org/download-linux.html). Additionally
+you will need the [GNU C compiler](http://gcc.gnu.org) (`gcc`) and
 [GNU Make](http://www.gnu.org/software/make/) (`make`). Both should be available
-for your Linux distribution through its package manager.
+for your Linux distribution through its package manager. For example, Ubuntu
+includes these tools in the `build-essential` package.
 
 #### Windows
 
@@ -35,12 +36,11 @@ building `meta-gtk-osx-bootstrap` and `meta-gtk-osx-core`, you need to build
 `meta-gtk-osx-themes`. Note that the entire compiling process can easily take
 30 minutes or more and ultimately consume nearly 1GB of disk space.
 
-## Download
-
-Download the `textadept_x.x.src.zip`, regardless of what platform you are on.
-
 ## Compiling
 
+Make sure you downloaded the `textadept_x.x.src.zip` (regardless of what
+platform you are on) and not a platform-specific binary package.
+
 #### Linux and BSD
 
 For Linux systems, simply run `make` in the `src/` directory. The `textadept`
diff --git a/doc/manual/2_Installation.md b/doc/manual/2_Installation.md
index e4f9a2b7..397f227a 100644
--- a/doc/manual/2_Installation.md
+++ b/doc/manual/2_Installation.md
@@ -48,6 +48,17 @@ Unpack the archive anywhere. Run Textadept by running
 symlink to the executable in your `PATH` (e.g. `/usr/bin`) or make a GNOME, KDE,

 XFCE, etc. button or menu launcher.

 

+##### Problems

+

+It is difficult to provide a single binary that runs on all Linux platforms

+since the versions of software installed vary widely from distribution to

+distribution. Because the Linux version of Textadept uses the version of GTK

+installed on your system, an error like: `error while loading shared  libraries:

+<lib>: cannot open shared object file: No such file or directory` may occur when

+trying to run the program. If this happens, do not be alarmed, the solution is

+actually quite painless even though it requires recompiling Textadept. See the

+[compiling](12_Compiling.html) page for more information.

+

 #### Mac OSX

 

 Unpack the archive and move `textadept.app` to your user or system