Update MS-Windows installation instructions for librsvg.

3 files changed, 140 insertions, 22 deletions

diff --git a/nt/ChangeLog b/nt/ChangeLog
index 8c1e928036c..feaf2cd7833 100644
--- a/nt/ChangeLog
+++ b/nt/ChangeLog
@@ -1,3 +1,9 @@
+2013-12-23  Eli Zaretskii  <eliz@gnu.org>
+
+        * README.W32:
+        * INSTALL: Update instructions for downloading and using image
+        libraries in general, and librsvg in particular.
+
 2013-12-16  Eli Zaretskii  <eliz@gnu.org>
 
         * emacs-x64.manifest:
diff --git a/nt/INSTALL b/nt/INSTALL
index 434327b66cc..0aca9b8980f 100644
--- a/nt/INSTALL
+++ b/nt/INSTALL
@@ -534,7 +534,11 @@ Windows 9X as well).
   For PNG images, we recommend to use versions 1.4.x and later of
   libpng, because previous versions had security issues.  You can find
   precompiled libraries and headers on the GTK download page for
-  Windows (http://www.gtk.org/download/win32.php).
+  Windows (http://www.gtk.org/download/win32.php for 32-bit builds and
+  http://www.gtk.org/download/win64.php for 64-bit builds).  The
+  ezwinports site, http://sourceforge.net/projects/ezwinports/files/
+  also offers PNG (as well as other image libraries), which are
+  usually newer.
 
   Versions 1.4.0 and later of libpng are binary incompatible with
   earlier versions, so Emacs will only look for libpng libraries which
@@ -563,11 +567,98 @@ Windows 9X as well).
   libraries that are known to be compatible with the version given by
   `libgif-version'.
 
-  Binaries for the other image libraries can be found at the GnuWin32
-  project.  Note specifically that, due to some packaging snafus in
-  the GnuWin32-supplied image libraries, you will need to download
-  _source_ packages for some of the libraries in order to get the
-  header files necessary for building Emacs with image support.
+  Pre-built versions of librsvg and its dependencies can be found in
+  one of these places:
+
+  1. http://sourceforge.net/projects/ezwinports/files/
+
+     This site includes a minimal (as much as possible for librsvg)
+     build of the library and its dependencies; it is also more
+     up-to-date with the latest upstream versions.  However, it
+     currently only offers 32-bit builds.  For building Emacs, you
+     need to download from this site all of the following *-bin.zip
+     archives:
+
+       librsvg, gdk-pixbuf, cairo, glib
+
+     The 'bin' archives on this site include both header files and the
+     libraries needed for building with librsvg and for running Emacs.
+     The librsvg archive includes all the shared libraries needed to
+     run Emacs with SVG support; the other 3 packages are required
+     because the compiler needs to see their header files when
+     building Emacs.
+
+  2. GTK project download site for Windows (see above for 2 URLs,
+     either for 32-bit builds or 64-bit builds)
+
+     This is the official Windows download site of the GTK project.
+     Its builds of librsvg are fatter, but are currently the only
+     alternative for 64-bit builds.  The easiest way to obtain the
+     dependencies required for building from this site is to download
+     a pre-bundled GTK+ development environment for Windows.  If you
+     would nevertheless like to download only the packages that are
+     strictly required, then, as of the time of this writing, here's
+     the list of GTK+ packages you will need:
+
+        librsvg, pango, freetype-2.4.11, freetype-2.4.2, croco, cairo,
+        glib, gdk-pixbuf, fontconfig, libpng-1.4.x, libpng-1.5.x,
+        libffi, libxml2, zlib
+
+     The GTK download page provides 2 separate archives for each
+     package: a 'bin' (binary) archive with programs and DLLs, and a
+     'dev' (development) archive with header files, import libraries,
+     and pkg-config files; download and install both archives for each
+     package you need.  (Sources of each package are available in a
+     separate, 3rd archive.)
+
+     As you see, some libraries for using this site's librsvg are
+     needed in more than one version -- this is because librsvg and
+     some of its dependencies were linked against different versions
+     of those libraries, and will look only for those DLLs when you
+     invoke SVG function.  So there's a bit of "DLL hell" involved
+     here, but at least in theory this should work, as each library
+     will dynamically link only against its dependencies, even if
+     another version of the same library is already loaded.  In
+     particular, at least 2 different versions of libpng will have to
+     be installed on your machine.  When you install these libpng
+     versions, be sure to keep the header files and the pkg-config
+     files in sync, i.e. install both the 'bin' and 'dev' archives of
+     the same libpng version together.
+
+  To use librsvg at runtime, ensure that librsvg and its dependencies
+  are on your PATH, or in the same directory as the emacs.exe binary.
+  If you are downloading from the ezwinports site, you only need to
+  install a single archive, librsvg-X.Y.Z-w32-bin.zip, which includes
+  all the dependency DLLs.  For the GTK project site, download the
+  'bin' archives for each of the libraries mentioned above.
+
+  If you think you've got all the dependencies and SVG support is
+  still not working, check your PATH for other libraries that shadow
+  the ones you downloaded.  Libraries of the same name from different
+  sources may not be compatible, this problem was encountered in the
+  past, e.g., with libcroco from gnome.org.
+
+  If you can see etc/images/splash.svg, then you have managed to get
+  SVG support working.  Congratulations for making it through DLL hell
+  to this point.  For some SVG images, you'll probably see error
+  messages from Glib about failed assertions, or warnings from Pango
+  about failure to load fonts (installing the missing fonts should fix
+  the latter kind of problems).  Problems have been observed in some
+  images that contain text, they seem to be a problem in the Windows
+  port of Pango, or maybe a problem with the way Cairo or librsvg is
+  using it that doesn't show up on other platforms.  However, Emacs
+  should not crash due to these issues.  If you eventually find the
+  SVG support too unstable to your taste, you can rebuild Emacs
+  without it by specifying the --without-rsvg switch to the configure
+  script.
+
+  Binaries for the other image libraries can be found on the
+  ezwinports site or at the GnuWin32 project (the latter are generally
+  very old, so not recommended).  Note specifically that, due to some
+  packaging snafus in the GnuWin32-supplied image libraries, you will
+  need to download _source_ packages for some of the libraries in
+  order to get the header files necessary for building Emacs with
+  image support.
 
 * Optional GnuTLS support
 
diff --git a/nt/README.W32 b/nt/README.W32
index 2b546428c6b..a397296b22b 100644
--- a/nt/README.W32
+++ b/nt/README.W32
@@ -20,12 +20,8 @@ See the end of the file for license conditions.
 
 * Preliminaries
 
-  Along with this file should be five subdirectories (bin, etc, info,
-  lisp, site-lisp).  If you have downloaded the barebin
-  distribution, then it will contain only the bin directory and the
-  built in documentation in etc/DOC, the rest of the subdirectories
-  are in the src distribution, which the barebin distribution is
-  designed to be used with.
+  Along with this file should be four subdirectories (bin, libexec,
+  share, and var).
 
 * Setting up Emacs
 
@@ -99,15 +95,18 @@ See the end of the file for license conditions.
   + addpm.exe - A basic installer that creates Start Menu icons for Emacs.
     Running this is optional.
 
-  + cmdproxy.exe - Used internally by Emacs to work around problems with
-    the native shells in various versions of Windows.
-
   + ctags.exe, etags.exe - Tools for generating tag files.  See the
     `Tags' node of the Emacs manual.
 
   + ebrowse.exe - A tool for generating C++ browse information.  See the
     `Ebrowse' manual.
 
+  Several helper programs are in a version-specific subdirectory of
+  the libexec directory:
+
+  + cmdproxy.exe - Used internally by Emacs to work around problems with
+    the native shells in various versions of Windows.
+
   + ddeclient.exe - A tool for interacting with DDE servers.  To be
     invoked as "ddeclient SERVER [TOPIC]", where SERVER is the DDE
     server name, and sends each line of its standard input to the DDE
@@ -122,12 +121,27 @@ See the end of the file for license conditions.
     a mail spool or POP server to a local user mailbox.  See the
     `Movemail' node of the Emacs manual.
 
+  + profile.exe - A helper program that generates periodic events for
+    profiling Emacs Lisp code.
+
+  + update-game-score.exe - A utility for updating the score files of
+    Emacs games.
+
 * Image support
 
   Emacs has built in support for XBM and PPM/PGM/PBM images, and the
-  libXpm library is bundled, providing XPM support (required for color
-  toolbar icons and splash screen).  Source for libXpm should be available
-  on the same place as you got this binary distribution from.
+  libraries.  These libraries are all available on the following sites:
+
+  1. http://sourceforge.net/projects/ezwinports/files/
+     -- leaner, more up-to-date builds, only for 32-bit Emacs
+  2. http://www.gtk.org/download/win32.php
+     http://www.gtk.org/download/win64.php
+     -- GTK project site; offers much fatter builds, but includes 64-bit
+        DLLs
+  3. GnuWin32 project -- very old builds, not recommended
+
+  Emacs will find these libraries if the directory they are installed
+  in is on the PATH.
 
   Emacs can also support some other image formats with appropriate
   libraries.  These libraries are all available as part of GTK
@@ -136,7 +150,7 @@ See the end of the file for license conditions.
   they are installed in is on the PATH.
 
       PNG: requires the PNG reference library 1.4 or later, which will
-      be named libpng14.dll or libpng14-14.dll.  LibPNG requires zlib,
+      be named libpngNN.dll or libpngNN-NN.dll.  LibPNG requires zlib,
       which should come from the same source as you got libpng.
       Starting with Emacs 23.3, the precompiled Emacs binaries are
       built with libpng 1.4.x and later, and are incompatible with
@@ -151,7 +165,14 @@ See the end of the file for license conditions.
       or libtiff.dll.
 
       GIF: requires libungif or giflib 4.1 or later, which will be
-      called giflib4.dll, libungif4.dll or libungif.dll.
+      called libgif-6.dll, giflib4.dll, libungif4.dll or libungif.dll.
+
+      SVG: requires librsvg 2.x whose DLL will be called
+      librsvg-2-2.dll.  SVG also requires several dependency DLLs,
+      such as Pango, Cairo, and Glib, all of them found on the
+      above-mentioned sites.  If you download from the ezwinports
+      site, you need only librsvg-2.nn.x-bin.zip, it comes with all
+      the other dependencies bundled.
 
    If you have image support DLLs under different names, customize the
    value of `dynamic-library-alist'.
@@ -168,8 +189,8 @@ See the end of the file for license conditions.
   the relevant DLLs during startup; failure to do so is not an error,
   but GnuTLS won't be available to the running session.
 
-  You can get pre-built binaries (including any required DLL and the
-  header files) at http://sourceforge.net/projects/ezwinports/files/.
+  You can get pre-built binaries (including any dependency DLLs) at
+  http://sourceforge.net/projects/ezwinports/files/.
 
 * libxml2 support