Index: /gs2-extensions/xpdf-tools/trunk/src/packages/CASCADE-MAKE/XPDFTOOLS.sh
===================================================================
--- /gs2-extensions/xpdf-tools/trunk/src/packages/CASCADE-MAKE/XPDFTOOLS.sh	(revision 32247)
+++ /gs2-extensions/xpdf-tools/trunk/src/packages/CASCADE-MAKE/XPDFTOOLS.sh	(revision 32248)
@@ -19,11 +19,5 @@
 export LDFLAGS="$LDFLAGS -L$GEXTXPDFTOOLS_INSTALLED/lib"
 
-# For Mac OSX, when -static is passed in for linking, we end up with the error "ld: library not found for -lcrt0.o"
-# See https://stackoverflow.com/questions/3801011/ld-library-not-found-for-lcrt0-o-on-osx-10-6-with-gcc-clang-static-flag
-# On Mac OSX, compile it with -Bstatic instead, as per https://stackoverflow.com/questions/844819/how-to-static-link-on-os-x
-# We will pass in the correct static variant as the custom GSDLFLAG_STATIC, so it will be set to either "-static" (for linux)
-# or "-Bstatic" for darwin when CMake starts compiling up xpdf-tools. When the GSDLFLAG_STATIC is set, it will also trigger
-# the branch of the gs-CMakeLists.txt code that does static compiling. If not set, xpdf-tools are compiled against dynamically
-# linked libraries.
+# See section D, 4c of the GS-README of this extension.
 if [ "x$GSDLOS" == "xdarwin" ] ; then
     static_flag=-Bstatic
@@ -103,33 +97,21 @@
 fi
 
-# If compiling statically, need these above in place of the references to .so files
+## If compiling statically make sure the above CMake command contains the following
+## with these values:
 #	    -DZLIB_LIBRARY=$prefix/lib/libz.a \
 #	    -DPNG_LIBRARY=$prefix/lib/libpng15.a \
 #	    -DFREETYPE_LIBRARY=$prefix/lib/libfreetype.a \
-# And throw in -DGSDLFLAG_STATIC_BUILD="-static" for linux or with "-Bstatic" for Macs
-# In place of FREETYPE_LIBRARY, could also try the following (then check built bins
-# by running ldd and file over them):
-##	    -DFREETYPE_DIR=$prefix \
+# and
+#	    -DGSDLFLAG_STATIC="$static_flag" \
 
 
-## When -DFREETYPE_DIR is used in place of -DFREETYPE_LIBRARY above, it makes
-## xpdf-tools compilation find the "libfreetype.so" (no versioning at end) in
-## our gs ext.
-## But -DZLIB_DIR and -DPNG_DIR are ignored because they go unrecognised, whereas
-## -DZLIB_LIBRARY and -DPNG_LIBRARY are recognised by XpdfTools' CMake files.
-## -DZLIB_LIBRARY and -DPNG_LIBRARY require full paths. So the first 2 lines of the
-## following won't work:
-#	    -DZLIB_DIR=$prefix \
-#	    -DPNG_DIR=$prefix \
-#	    -DFREETYPE_DIR=$prefix \
-
-## When specified in the following way, all 3 lines are recognised (freetype, zlib,
-## png). The 3rd line can alternatively still use "-DFREETYPE_DIR=$prefix"
+## For building dynamic xpdf-tools executables, change the above to have the following instead:
 #	    -DZLIB_LIBRARY=$prefix/lib/libz.so.1.2.7 \
 #	    -DPNG_LIBRARY=$prefix/lib/libpng15.so.15.30.0 \
 #	    -DFREETYPE_LIBRARY=$prefix/lib/libfreetype.so.6.3.20 \
-# The above is for building dynamic xpdf-tools executables. For which, also don't
-# pass in -DGSDLFLAG_STATIC_BUILD="..." (remove the line, don't comment it out, nor
-# set the value to "")
+# (The 3rd line can alternatively be "-DFREETYPE_DIR=$prefix")
+# And remove the following line. Don't comment it out, nor set it to "", but remove it:
+#	    -DGSDLFLAG_STATIC="$static_flag" \
+
 
 # If compilation was successful, then we don't need cmake binaries anymore when
Index: /gs2-extensions/xpdf-tools/trunk/src/packages/GS-README.txt
===================================================================
--- /gs2-extensions/xpdf-tools/trunk/src/packages/GS-README.txt	(revision 32247)
+++ /gs2-extensions/xpdf-tools/trunk/src/packages/GS-README.txt	(revision 32248)
@@ -1,47 +1,397 @@
--------------------------------------------------------------------
-Modfications to xpdf-4.00.tar.gz to produce gs-xpdf-4.00.tar.gz
--------------------------------------------------------------------
-In order to successfully compile xpdf-tools-4.00 against *dynamically* linked libraries for zlib (and libpng), needed to modify the CMakeLists.txt. The changes.
-
-	if (PNG_FOUND)
-	  include_directories("${PNG_INCLUDE_DIRS}")
-	  add_definitions("${PNG_DEFINITIONS}")
-	endif ()
-	#--------- NEW
-	# https://stackoverflow.com/questions/36126333/mingw-cmake-undefined-reference-to-zlib
-	if (ZLIB_FOUND)
-	  include_directories("${ZLIB_INCLUDE_DIRS}")
-	  add_definitions("${ZLIB_DEFINITIONS}")
-	endif ()
-	#--------- ENDNEW
-	if (HAVE_LCMS)
+__________________________________________________________
+A. XPDF
+__________________________________________________________
+
+Xpdf's last mod date is in 2017 and it includes its own pdftohtml utility tool, whereas the old "pdftohtml" tool that GS used was last updated 2013 (and itself made use of Xpdf, possible older versions).
+
+The tool takes a PDF and produces an HTML file for each page of the PDF, consisting of selectable HTML text overlaid on top of "screenshot" image of the page. (A page's text is not part of the screenshot.)
+
+1. https://www.xpdfreader.com/download.html
+
+As per the Readme file found in the linux binary of Xpdf Tools, the Xpdf Viewer requires the qt toolkit, but not the Xpdf Tools. Have not read the Install file to confirm whether the same is the case for when compiling the command line tools. (But in that case, can't we just include the tools binary available for all 3 OS, instead of compiling on each platform)
+
+	- Using Xpdf's pdftohtml tool:
+	greenstone@bedrock:~/Downloads/xpdf-tools-linux-4.00/bin64$./pdftohtml -z 1.5 ~/Downloads/ApacheLicence.pdf licence
+
+		where licence is a folder.
+
+	- Using Xpdf's pdftotext tool:
+	greenstone@bedrock:~/Downloads/xpdf-tools-linux-4.00/bin64$./pdftotext -nopgbrk ~/Downloads/ApacheLicence.pdf ~/Downloads/ApacheLicence.txt
+
+		where the output text file must be specified with a full path name.
+
+
+2. Documentation on Xpdf-Tools:
+- https://www.xpdfreader.com/support.html
+	for example, the pdftohtml man page: https://www.xpdfreader.com/pdftohtml-man.html
+- https://linux.die.net/man/5/xpdfrc
+(Configuration flags you can put into ~/.xpdfrc to use as defaults when running xpdf tool commands)
+
+3. We're using Xpdf Tools version: xpdf-tools-linux-4.00
+
+4. We started by working with the ready-made Xpdf-tools binaries available for download from the xpdf site for Win, Linux and Mac.
+
+5. We're now moving to compiling up Xpdf-tools ourselves using CASCADE-MAKE, which we have so far got to successfully compile statically on Linux (LSB environment inclusive) to build working binaries. 
+
+On Mac, I've been unable to get it to produce statically linked libraries: at this stage they're dynamically linked.
+
+
+__________________________________________________________
+B. Mojo::DOM perl package for parsing HTML
+__________________________________________________________
+
+XPDF's pdftohtml conversion of a single PDF document produces multiple HTML files: one for each page in the source PDF.
+We want the output to be "paged_html": a single HTML file that is sectionalised, each section representing a page of the
+original PDF.
+
+We need to be able to parse the many HTML pages produced by XPDF's pdftohtml conversion of a doc, in order to massage the output
+into the single sectionalised HTML file. For this we needed a HTML parser package for Perl.
+
+1. Before Dr Bainbridge found Mojo::DOM, he looked at
+* https://en.wikipedia.org/wiki/Comparison_of_HTML_parsers
+* http://radar.oreilly.com/2014/02/parsing-html-with-perl-2.html
+
+2. Main links for Mojo::DOM
+* https://mojolicious.org/perldoc/Mojo/DOM
+* https://metacpan.org/pod/Mojo::DOM
+	Dependencies: http://deps.cpantesters.org/?module=Mojo%3A%3ADOM;perl=latest
+
+3. Once you've downloaded Mojo::DOM's src, follow Dr Bainbridge's sequence of commands for building the Mojo::DOM CPAN module of perl below.
+We'll be using this module to be used for parsing the HTML output by XPDF tool pdftohtml
+
+
+	mkdir cpan
+	 2020  tar xvzf Mojolicious-7.84.tar.gz 
+	 2021  cd Mojolicious-7.84/
+	 2028  perl ./Makefile.PL PREFIX=`pwd`/installed
+	 2030  make
+	 2031  make install
+	 2033  cp -r installed/share/perl/5.18.2 ../cpan
+	cd ..
+	 2044  export PERL5LIB=`pwd`/cpan
+
+	 2053  emacs -nw test.pl
+
+	#!/usr/bin/perl -w
+	add in 'use v5.10;'
+	 
+	 2054  chmod a+x test.pl
+	 2055  ./test.pl 
+
+
+__________________________________________________________
+C. Compiling Xpdf-Tools: statically or dynamically linked
+__________________________________________________________
+
+As explained in detail in section D below, gs-CMakeLists.txt allows us to compile xpdf-tools statically (as we've now set it up for by default) or dynamically (as its CMake makefiles were originally set up for).
+
+1. To compile Xpdf-Tools statically, packages/CASCADE-MAKE/XPDFTOOLS.sh should contain:
+
+	cmake -DCMAKE_BUILD_TYPE=Release \
+	    -DCMAKE_INSTALL_PREFIX=$prefix \
+	    -DZLIB_LIBRARY=$prefix/lib/libz.a \ 	 	# <========= THIS
+	    -DPNG_LIBRARY=$prefix/lib/libpng15.a \		# <========= THIS
+	    -DFREETYPE_LIBRARY=$prefix/lib/libfreetype.a \	# <========= THIS
+	    -DCMAKE_DISABLE_FIND_PACKAGE_Qt4=1 \
+	    -DCMAKE_DISABLE_FIND_PACKAGE_Qt5Widgets=1 \
+	    -DCMAKE_C_FLAGS="$CFLAGS" \
+	    -DCMAKE_CXX_FLAGS="$CXXFLAGS" \
+	    -DCMAKE_EXE_LINKER_FLAGS="$LDFLAGS" \
+	    -DGSDLFLAG_STATIC="$static_flag" \			# <========= THIS
+	    $GEXT_XPDFTOOLS/packages/$package$version
+
+In place of FREETYPE_LIBRARY above, could also try the following, 
+	    -DFREETYPE_DIR=$prefix \
+but then check the built binaries by running "ldd" and "file" over them, to make sure they're not referencing any .so dynamic link libraries:
+
+
+2. To compile Xpdf-Tools dynamically and make it find *our* dynamically linked libraries for its helper packages zlib, libpng and freetype, edit packages/CASCADE-MAKE/XPDFTOOLS.sh to contain:
+
+	cmake -DCMAKE_BUILD_TYPE=Release \
+	    -DCMAKE_INSTALL_PREFIX=$prefix \
+	    -DZLIB_LIBRARY=$prefix/lib/libz.so.1.2.7 \			# <========= THIS
+	    -DPNG_LIBRARY=$prefix/lib/libpng15.so.15.30.0 \		# <========= THIS
+	    -DFREETYPE_LIBRARY=$prefix/lib/libfreetype.so.6.3.20 \	# <========= THIS
+	    -DCMAKE_DISABLE_FIND_PACKAGE_Qt4=1 \
+	    -DCMAKE_DISABLE_FIND_PACKAGE_Qt5Widgets=1 \
+	    -DCMAKE_C_FLAGS="$CFLAGS" \
+	    -DCMAKE_CXX_FLAGS="$CXXFLAGS" \
+	    -DCMAKE_EXE_LINKER_FLAGS="$LDFLAGS" \
+	    $GEXT_XPDFTOOLS/packages/$package$version		# <=== -DGSDLFLAG_STATIC removed
+
+
+
+	(1) In the above, you could also set 
+		-DFREETYPE_DIR=$prefix
+	in place of
+		-DGSDLFLAG_STATIC="$static_flag"
+
+	In that case it makes, xpdf-tools compilation find the "libfreetype.so" (no versioning at end) in our gs2-extension.
+	After successfully building, make sure to have sourced the gs2-extension's setup.bash before running "ldd" over the
+	generated xpdf-tools binaries, in order to let it use the $LD_LIBRARY_PATH we set to find our .so files.
+
+	(2) Note that there are no equivalent for ZLIB and LIBPNG: doing -DZLIB_DIR=$prefix or -DPNG_DIR=$prefix will be
+	ineffective, as neither are recognised by xpdf-tools' CMake set up.
+
+__________________________________________________________
+D. How we got Xpdf-Tools to compile using CASCADE-MAKE
+__________________________________________________________
+
+The process:
+
+1. We set up a CASCADE-MAKE GS2-extension "xpdf-tools" at trac.greenstone.org/browser/gs2-extensions/xpdf-tools/trunk/src
+Be aware that its lowercased "cascade-make" subfolder is an svn external, the original is at http://trac.greenstone.org/browser/other-projects/cascade-make/trunk/
+
+So far, this CASCADE-MAKE project includes the Xpdf-Tools source tarball, its helper packages zlib, libpng and freetype, as well as CMake to compile the Xpdf-Tools source code.
+The next step is to include JPEG and TIFF libraries too.
+
+2a. We downloaded the Xpdf-Tools source tarball, xpdf-4.00.tar.gz, from the xpdf site at https://www.xpdfreader.com/download.html under section "Download the Xpdf source code".
+
+The xpdf-tools source code tarball consists of the source for Xpf-tools and Xpdf (Xpdf-Reader). The Xpdf-Reader additionally requires Qt to build and run, but we don't want the Xpdf-Reader, just Xpdf-Tools.
+
+b. Compiling Xpdf-Tools fron source and running them requires the following packages and libraries, as per the xpdf-tools source code INSTALL file:
+
+To build xpdf-tools:
+- CMake 2.8.8 or newer 
+
+Libraries to link against and used by xpdf-tools:
+- FreeType 2.0.5 or newer
+- libpng (for pdftoppm and pdftohtml)
+- zlib (for pdftoppm and pdftohtml)
+
+
+3. Compilation of xpdf-tools worked with CMake 3.11.4 on the linux resnet machine. However, CMake 3.11.3 itself failed to compile in the LSB environment and on the Mac Mountain Lion machine because of a version incompatibility between the older g++ installed there and the advanced version of CMake 3.11.4.
+
+CMake version 3.9.6 however is supposed to be compatible with older versions of g++, as per https://stackoverflow.com/questions/47886400/cmake-configure-error-in-3-10-1-but-not-in-3-9-6
+To avoid installing newer versions of g++ and clang in the LSB virtual machine and the Mac, I've shifted the CMake version back to version 3.9.6, still 
+
+
+4a. On building xpdf-tools to work with dynamically linked libs found anywhere.
+
+If compiling xpdf-tools against dynamic linked libraries for these packages, then the basic CMake command in packages/CASECADE-MAKE/XPDFTOOLS.sh can look like:
+	cmake -DCMAKE_BUILD_TYPE=Release \
+	    -DCMAKE_INSTALL_PREFIX=$prefix \
+	    -DCMAKE_DISABLE_FIND_PACKAGE_Qt4=1 \
+	    -DCMAKE_DISABLE_FIND_PACKAGE_Qt5Widgets=1 \
+	    -DCMAKE_C_FLAGS="$CFLAGS" \
+	    -DCMAKE_CXX_FLAGS="$CXXFLAGS" \
+	    -DCMAKE_EXE_LINKER_FLAGS="$LDFLAGS" \
+	    $GEXT_XPDFTOOLS/packages/$package$version 	# Note: no -DGSDLFLAG_STATIC=...
+
+With the above, the xpdf-tools source code and its make files work out of the box.
+
+4b. On building xpdf-tools to work with the dynamically linked libs for freetype libpng, zlib that we produce when cascade-making the xpdf-tools gs2-extension.
+
+Since we're compiling up freetype, libpng and zlib packages as part of the Xpdf-Tools GS2-extension with CASCADE-MAKE, the next step was to compile xpdf-tools by dynamically linking against our .so files for these 3 libraries. To do so, XPDFTOOL.sh should have the following changes
+
+	(1) set up CFLAGS, CXXFLAGS, CPPFLAGS and LDFLAGS to help linkage of xpdf-tools find our .so versions of the necessary libs:
+
+	export CFLAGS="$CFLAGS -I$GEXTXPDFTOOLS_INSTALLED/include -I$GEXTXPDFTOOLS_INSTALLED/include/libpng15"
+	export CPPFLAGS="$CPPFLAGS -I$GEXTXPDFTOOLS_INSTALLED/include -I$GEXTXPDFTOOLS_INSTALLED/include/libpng15"
+	export CXXFLAGS="$CXXFLAGS -I$GEXTXPDFTOOLS_INSTALLED/include -I$GEXTXPDFTOOLS_INSTALLED/include/libpng15"
+	export LDFLAGS="$LDFLAGS -L$GEXTXPDFTOOLS_INSTALLED/lib"
+
+	(2) The CMAKE command we run must pass the full paths to the actual .so library files (the ones with specific
+	versions in their files names) rather than the symbolically linked generally-named .so files (the latter won't
+	be found when building xpdf-tools and CMake will try to look for the .so library files elsewhere on the system):
+
+	cmake -DCMAKE_BUILD_TYPE=Release \
+	    -DCMAKE_INSTALL_PREFIX=$prefix \
+	    -DZLIB_LIBRARY=$prefix/lib/libz.so.1.2.7 \         		# <========= NEW
+	    -DPNG_LIBRARY=$prefix/lib/libpng15.so.15.30.0 \    		# <========= NEW
+	    -DFREETYPE_LIBRARY=$prefix/lib/libfreetype.so.6.3.20 \    	# <========= NEW
+	    -DCMAKE_DISABLE_FIND_PACKAGE_Qt4=1 \
+	    -DCMAKE_DISABLE_FIND_PACKAGE_Qt5Widgets=1 \
+	    -DCMAKE_C_FLAGS="$CFLAGS" \
+	    -DCMAKE_CXX_FLAGS="$CXXFLAGS" \
+	    -DCMAKE_EXE_LINKER_FLAGS="$LDFLAGS" \
+	    $GEXT_XPDFTOOLS/packages/$package$version	# Again: no -DGSDLFLAG_STATIC=...
+
+Further, the "xpdf/CMakeLists.txt" file within the xpdf-4.00.tar.gz source code tarball needs to be modified to refer to ZLIB_LIBRARIES when linking pdftops and pdftoppm. The linking commands for *both* the "pdftops" and "pdftoppm" executable targets in xpdf/CMakeLists.txt should look like the following, 
+
+	    target_link_libraries(pdftoppm goo fofi splash
+                        ${FREETYPE_LIBRARY} ${FREETYPE_OTHER_LIBS}
+                        ${DTYPE_LIBRARY}
+                        ${LCMS_LIBRARY}
+			${ZLIB_LIBRARIES})				# <========= NEW
+
+
+	(3) Since CMakeLists.txt has been modified, we initially renamed the xpdf src tarball to gs-xpdf-4.00.tar.gz.
+	However, the current version works with the regular downloaded xpdf-4.00.tar.gz tarball. But after extraction,
+	XPDFTOOLS.sh copies across the custom packages/gs-CMakeLists.txt into the extracted tarball's xpdf subdirectory,
+	renaming the file as CMakeLists.txt (so the path to it becomes "xpdf-4.00/xpdf/CMakeLists.txt"). In XPDFTOOLS.sh:	
+
+	# patch the original tarball with our custom makefile
+	if [[ -d "$package$version/xpdf" && -f "gs-CMakeLists.txt" ]]; then
+	    echo "*******************************************************************"
+	    echo "Using our custom gs-CMakeLists.txt instead of the one included in $package$version"
+	    echo "Renaming gs-CMakeLists.txt to $package$version/xpdf/CMakeLists.txt"
+	    echo "*******************************************************************"
+
+	    cp "gs-CMakeLists.txt" "$package$version/xpdf/CMakeLists.txt"
+	fi
+
+
+4c. On building static xpdf-tools binaries using the static *.a freetype libpng, zlib libraries that we produce when cascade-making the xpdf-tools gs2-extension.
+
+In order to compile up xpdf-tools *statically*, so that it builds against the static *.a libraries of freetype, libpng and zlib that we produce during the gs2-extension's CASCADE-MAKE process, we have to make further modifications. 
+
+	(1) First, the XPDFTOOLS.sh cascade-make file should pass the full paths to the actual (non-symbolic link) .a file for each library.
+	A custom GS flag, GSDLFLAG_STATIC, is also invented in gs-CMakeLists.txt and assigned "-static for linux
+	and "-Bstatic" for Mac, to pass in during the linking stage of building xpdf-tools.
+
+	For Mac OSX, when -static is passed in for linking as on linux, this produced the error
+	"ld: library not found for -lcrt0.o" during the build of the xpdf-tools package. For information, see
+	https://stackoverflow.com/questions/3801011/ld-library-not-found-for-lcrt0-o-on-osx-10-6-with-gcc-clang-static-flag
+	The page https://stackoverflow.com/questions/844819/how-to-static-link-on-os-x mentions compiling
+	with -Bstatic on Mac OSX instead. To do so, XPDFTOOLS.sh passes in the GSDLFLAG_STATIC set to either
+	"-static" (for linux) or "-Bstatic" for darwin.
+	However the last mentioned stackoverflow page also says that -Bstatic is a no-op, and this appears to be
+	the case when "otool -L" is run over the generated xpdf-tools binaries: the binaries are all dynamically
+	linked. Although they're finding our .so files of freetype, libpng and zlib, they're not finding the .a
+	versions, even though XPDFTOOLS.sh tries to point gs-CMakeLists.txt to the correct .a files. 
+
+	The new modifications to XPDFTOOLS.sh:
+
+	if [ "x$GSDLOS" == "xdarwin" ] ; then
+	    static_flag=-Bstatic
+	else
+	    static_flag=-static
+	fi
+
 	...
-
-
-Note that the xpdftools binaries produced in this fashion are still linked to the system zlib and libpng rather than the ones we're compiling up as part of the GEXT XPDFTOOLS extension. But just to get the compilation to succeed with the references to our local library in XPDFTOOLS.sh below (a step toward getting the statically linked xpdftools binaries to compile), we needed the above changes.
-
-	cmake -DCMAKE_BUILD_TYPE=Release \
-	    -DCMAKE_INSTALL_PREFIX=$prefix \
-	    -DZLIB_LIBRARY=$prefix/lib/libz.a \ <========
-	    -DPNG_LIBRARY=$prefix/lib/libpng15.a \ <========
-	    -DFREETYPE_LIBRARY=$prefix/lib/libfreetype.a \ <========
-	    -DCMAKE_DISABLE_FIND_PACKAGE_Qt4=1 \
-	    -DCMAKE_DISABLE_FIND_PACKAGE_Qt5Widgets=1 \
-	    -DCMAKE_C_FLAGS="$CFLAGS" \
-	    -DCMAKE_CXX_FLAGS="$CXXFLAGS" \
-	    -DCMAKE_EXE_LINKER_FLAGS="$LDFLAGS" \
-	    -DPNG_LINK_FLAGS="-lpng15" \
+	cmake -DCMAKE_BUILD_TYPE=Release \
+	    -DCMAKE_INSTALL_PREFIX=$prefix \
+	    -DZLIB_LIBRARY=$prefix/lib/libz.a \         		# <========= MODIFIED TO .a
+	    -DPNG_LIBRARY=$prefix/lib/libpng15.a \         		# <========= MODIFIED TO .a
+	    -DFREETYPE_LIBRARY=$prefix/lib/libfreetype.a \         	# <========= MODIFIED TO .a
+	    -DCMAKE_DISABLE_FIND_PACKAGE_Qt4=1 \
+	    -DCMAKE_DISABLE_FIND_PACKAGE_Qt5Widgets=1 \
+	    -DCMAKE_C_FLAGS="$CFLAGS" \
+	    -DCMAKE_CXX_FLAGS="$CXXFLAGS" \
+	    -DCMAKE_EXE_LINKER_FLAGS="$LDFLAGS" \
+ 	    -DGSDLFLAG_STATIC="$static_flag" \         			# <========= NEW
 	    $GEXT_XPDFTOOLS/packages/$package$version
 
-
--------------------------------------------------------------------
-Redundant CMakeLists.txt files
--------------------------------------------------------------------
-I've also committed work in progress versions of CMakeLists.txt
-- CMakeLists.txt.orig: the original version of this file in the unmodified xpdf-4.00.tar.gz
-- CMakeLists.txt.static1_notworking: Sets up CMake settings for static compilation. Which then required some further changes to stop compilation from complaining about undefined references to thread mutex or something. (-lpthread/pthread library was necessary, but needed to set this the CMake way). Not a working version.
-- CMakeLists.txt.static2_notworking: more changes in an attempt to bypass the errors about undefined references to png (and 'inflate' of zlib). Still not working. It's this version that briefly attempted to use the override to PNG_LINK_FLAGS I am setting in XPDFTOOLS.sh (the line containing: -DPNG_LINK_FLAGS="-lpng15" \). Not sure why it never got set.
-- CMakeLists.txt: the version of this file first committed with the modified gs-xpdf-4.00.tar.gz. For getting xpdf-tools to compile with dynamic linking and with the current setup of XPDFTOOLS.sh
-
-There are comments in the modified CMakeLists.txt file above to provide URLs explaining why I made various changes.
-
+	(2) Our customised gs-CMakeLists.txt file now checks for this flag GSDLFLAG_STATIC being set and, if it is,
+	uses it during the linking stage. As in (1) above, it will be set to "-static" for Linux and "-Bstatic" for Mac.
+	
+	- When the flag is set, the linking flags passed into each occurrence of target_link_libraries() in
+	gs-CMakeLists.txt is moreover manually written in the form of "-static -l<libs>" rather than using
+	the default linking commands inherited from the original CMakeLists.txt.
+	- If GSDLFLAG_STATIC isn't set, then we don't build statically, and the linking flags passed to each
+	target_link_libraries() are mostly the original ones.
+
+	For example,
+
+	    if(GSDLFLAG_STATIC)
+	        target_link_libraries(pdftoppm goo fofi splash
+	          ${GSDLFLAG_STATIC} -lfreetype ${DTYPE_LIBRARY} ${LCMS_LIBRARY} -lz -lm -lc -lpthread)
+	    else ()
+	        target_link_libraries(pdftoppm goo fofi splash
+		                    ${FREETYPE_LIBRARY} ${FREETYPE_OTHER_LIBS}
+		                    ${DTYPE_LIBRARY}
+		                   ${LCMS_LIBRARY}
+				    ${ZLIB_LIBRARIES})
+	    endif ()
+
+	DETAILED EXPLANATION:
+	We found that when building *statically*, gs-CMakeLists.txt needed to NOT use the PNG_LIBRARIES, ZLIB_LIBRARIES
+	and FREETYPE_LIBRARY in its linker commands, target_link_libraries(), as doing so produced partially dynamic
+	xpdf-tools executables which were moreover BROKEN. They wouldn't run, and in fact attempting to run an xpdf-tool,
+	like "./pdftohtml", would produce a file not found error. Something like "bash: no such file or directory".
+
+	Online discussions mentioned that this generally happened when attempting to run 32 bit executables on 64 bit
+	linux when 32 bit loaders are not installed. (In such cases, the solution was to apt-get install some 32 bit package.)
+	However, our broken binaries were all 64 bit, as indicated when running the "file" command on them. However, their
+	being further partially dynamically linked executables didn't imply that they would be broken, as we were eventually
+	able to produce partially dynamic executables that did work, before solving static linking altogether.
+
+	The real issue was that including references to  ${FREETYPE_LIBRARY} ${FREETYPE_OTHER_LIBS}, ${PNG_LIBRARIES} and
+	${ZLIB_LIBRARIES} in any target_link_libraries() resulted in the wrong linking command producing broken binaries.
+
+	Doing the regular target_link_libraries() in static mode results in building with 
+	"-Wl,-Bstatic -lfreetype -lpng15 -lz -Wl,-Bdynamic -lpthread" at end of link line
+	and produces broken binaries for pdftohtml/pdftoppm/pdftops/pdftopng.
+
+	Note that PNG_LIBRARIES includes zlib/lz: "-lpng -lz", and along with freetype,
+	these are linked statically. However, Threads/lpthread is included as a dynamically
+	linked library instead of including a .a (regardless of whether it's appended
+	as -lpthread or Threads::Threads in the target_link_libraries()), contributing to
+	the pdfhtml binary produced being a partially static, partially dynamic one,
+	so a dynamic executable overall.
+
+	The order of dynamic .so files listed by ldd in the broken static binary of pdftohtml differs from
+	a manually statically linked working version of pdftohtml, and seems to be the only difference
+	between the two in ldd's output. Not using "-Wl,-Bstatic" and using -static (-Bstatic on Mac)
+	in its place creates a partially static dynamic executable that isn't broken, whereas
+	additionally removing "-Wl,-Bdynamic -lpthread" and replacing it with -lpthread
+	moreover produces a working pdftohtml that is a fully static linked executable.
+
+	The inclusion of the math lib and c lib (lm and lc) in the final link command
+	are to completely bypass the remaining .so dependencies that were present in
+	the executable and produce the fully static executable. The lm and lc libs were referenced
+	by all xpdf-tool binaries (as indicated when generating dynamic ones and running ldd over them)
+	but Dr Bainbridge said that -lm and -lc were some libs passed in by the compiler by default,
+	which would explain why explicitly setting them for some xpdftools and not other may not have
+	mattered.
+
+NOTES:
+Initial attempts at modifying gs-CMakeLists.txt for static compiling that proved to be unnecessary:
+
+	(1) Setting -static globally doesn't have a useful effect.
+
+	# We want to build static xpdf-tools binaries. See
+	# https://stackoverflow.com/questions/24648357/compiling-a-static-executable-with-cmake
+	# Want to make the min number of changes for building statically, so using the way
+	# below. Beware, must *append* "-static" to existing CMAKE_EXE_LINKER_FLAGS=LD_FLAGS
+	##SET(CMAKE_FIND_LIBRARY_SUFFIXES ".a")
+	##SET(BUILD_SHARED_LIBS OFF)
+	##SET(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -static")
+
+	The above 3 lines just add a -static before the "-O2 -Wall -fPIC -rdynamic ..." during linking, such as below.
+	But they have no further effect on whether static building actually succeeds or not. The only effective static
+	linking command (for Linux so far) was to pass -static in the target_link_libraries() command followed by the
+	"-l<libname>" for each library in the correct order.
+
+----
+/usr/bin/c++  -I/home/greenstone/gs3-svn-26Mar2018/gs2build/ext/xpdf-tools/trunk/src/linux/include  -I/home/greenstone/gs3-svn-26Mar2018/gs2build/ext/xpdf-tools/trunk/src/linux/include -I/home/greenstone/gs3-svn-26Mar2018/gs2build/ext/xpdf-tools/trunk/src/linux/include/libpng15 -O3 -Wall -fPIC  -L/home/greenstone/gs3-svn-26Mar2018/gs2build/ext/xpdf-tools/trunk/src/linux/lib  -L/home/greenstone/gs3-svn-26Mar2018/gs2build/ext/xpdf-tools/trunk/src/linux/lib -static ***** <- HERE ****** -O2 -Wall -fPIC -rdynamic CMakeFiles/pdftohtml.dir/HTMLGen.cc.o CMakeFiles/pdftohtml.dir/SplashOutputDev.cc.o CMakeFiles/pdftohtml.dir/TextOutputDev.cc.o CMakeFiles/pdftohtml.dir/pdftohtml.cc.o CMakeFiles/xpdf_objs.dir/AcroForm.cc.o CMakeFiles/xpdf_objs.dir/Annot.cc.o CMakeFiles/xpdf_objs.dir/Array.cc.o CMakeFiles/xpdf_objs.dir/BuiltinFont.cc.o CMakeFiles/xpdf_objs.dir/BuiltinFontTables.cc.o CMakeFiles/xpdf_objs.dir/Catalog.cc.o CMakeFiles/xpdf_objs.dir/CharCodeToUnicode.cc.o CMakeFiles/xpdf_objs.dir/CMap.cc.o CMakeFiles/xpdf_objs.dir/Decrypt.cc.o CMakeFiles/xpdf_objs.dir/Dict.cc.o CMakeFiles/xpdf_objs.dir/Error.cc.o CMakeFiles/xpdf_objs.dir/FontEncodingTables.cc.o CMakeFiles/xpdf_objs.dir/Form.cc.o CMakeFiles/xpdf_objs.dir/Function.cc.o CMakeFiles/xpdf_objs.dir/Gfx.cc.o CMakeFiles/xpdf_objs.dir/GfxFont.cc.o CMakeFiles/xpdf_objs.dir/GfxState.cc.o CMakeFiles/xpdf_objs.dir/GlobalParams.cc.o CMakeFiles/xpdf_objs.dir/JArithmeticDecoder.cc.o CMakeFiles/xpdf_objs.dir/JBIG2Stream.cc.o CMakeFiles/xpdf_objs.dir/JPXStream.cc.o CMakeFiles/xpdf_objs.dir/Lexer.cc.o CMakeFiles/xpdf_objs.dir/Link.cc.o CMakeFiles/xpdf_objs.dir/NameToCharCode.cc.o CMakeFiles/xpdf_objs.dir/Object.cc.o CMakeFiles/xpdf_objs.dir/OptionalContent.cc.o CMakeFiles/xpdf_objs.dir/Outline.cc.o CMakeFiles/xpdf_objs.dir/OutputDev.cc.o CMakeFiles/xpdf_objs.dir/Page.cc.o CMakeFiles/xpdf_objs.dir/Parser.cc.o CMakeFiles/xpdf_objs.dir/PDFDoc.cc.o CMakeFiles/xpdf_objs.dir/PDFDocEncoding.cc.o CMakeFiles/xpdf_objs.dir/PSTokenizer.cc.o CMakeFiles/xpdf_objs.dir/SecurityHandler.cc.o CMakeFiles/xpdf_objs.dir/Stream.cc.o CMakeFiles/xpdf_objs.dir/TextString.cc.o CMakeFiles/xpdf_objs.dir/UnicodeMap.cc.o CMakeFiles/xpdf_objs.dir/UnicodeTypeTable.cc.o CMakeFiles/xpdf_objs.dir/UTF8.cc.o CMakeFiles/xpdf_objs.dir/XFAForm.cc.o CMakeFiles/xpdf_objs.dir/XRef.cc.o CMakeFiles/xpdf_objs.dir/Zoox.cc.o  -o pdftohtml ../goo/libgoo.a ../fofi/libfofi.a ../splash/libsplash.a -static -lfreetype -lpng -lz -lm -lc -lpthread 
+----
+
+	(2) Threads::Threads instead of -lpthread results in a partially dynamic executable.
+
+	# The original, unmodified CMakeLists.txt was not set up sufficiently
+	# for static compilation of xpdf-tools. As a result, compile would first fail
+	# with errors about undefined refs to mutex / lpthread.
+	# When building xpdf-tools statically, need to add the following 2 lines as well
+	# as append "Threads::Threads" to the end of each "target_link_libraries(<list>)"
+	# See https://stackoverflow.com/questions/1620918/cmake-and-libpthread
+	# found googling cmake and "-lpthread" (pthread) after ERRORS to do with this, like:
+	#   undefined reference to `pthread_mutex_unlock'
+	##set(THREADS_PREFER_PTHREAD_FLAG ON)
+	##find_package(Threads REQUIRED)
+
+	In instances when compilation was successful, including the above 2 lines in combination with "Threads::Threads"
+	as the final argument to every target_link_libraries(...) occurrence in gs-CMakeLists.txt would only manage to
+	produce partially dynamically linked xpdftools binaries. (Depending on what the linking command was when building
+	Xpdf-Tools, the partially dynamically linked executables may work or may be broken. See explanation further above.)
+	We wanted fully statically linked binaries, for which we needed to pass in "-lpthread" as the trailing argument
+	to each target_link_libraries(...). So without either, compilation will fail. However, with "Threads::Threads"
+	the binaries weren't fully static, whereas with -lpthread the xpdftools executables were fully static as CMake no
+	longer tried to link against a dynamic Threads library.
+
+
+(5) To view the unmodified CMakeLists.txt included in the xpdf-4.00 source code tarball, untar it and look for its "xpdf/CMakeLists.txt" (not the toplevel file of the same name).
+Run a 'diff' against gs-CMakeLists.txt to see further differences, such as debug statements and comments. Most comments have been removed and placed into this readme file instead.
+
+
+(6) When CASCADE-MAKE is run on the xpdf-tools GS2-extension, it first compiles up CMake, needed to compile up xpdf-tools.
+Unlike the library packages like freetype, libpng and zlib that we also build for xpdf-tools as part of this gs2-extension, CMake's build products don't need to be included in the distribution tarball of our built xpdf-tools executables.
+
+There's a "move-cmake.sh" script in the xpdf-tools gs2-extension that can be run with the "away" and "back" options to move the CMake stuff out of the way (into a "devel" folder) after successfully building xpdf binaries and that can also be run to move them back if wanting to recompile.
+
+The script can be run manually, but it's also run by the extension:
+- packages/CASCADE-MAKE/XPDFTOOLS.sh runs "move-cmake.sh away" after xpdf-tools has been built, so that the extension's install location is ready for tarring up for distribution.
+- When recompiling the xpdf-tools extenion, the CASCADE-MAKE process will run packages/CASCADE-MAKE/CMAKE.sh file which in turn runs "move-cmake.sh back" if there's a prebuilt CMake which had earlier been moved out of the way.
+
+
Index: /gs2-extensions/xpdf-tools/trunk/src/packages/gs-CMakeLists.txt
===================================================================
--- /gs2-extensions/xpdf-tools/trunk/src/packages/gs-CMakeLists.txt	(revision 32247)
+++ /gs2-extensions/xpdf-tools/trunk/src/packages/gs-CMakeLists.txt	(revision 32248)
@@ -10,6 +10,10 @@
 
 #========================================================================
-# This is a customised version of Xpdf Tools' CMake file.
-# Customised for Greenstone.
+# This is a customised version of Xpdf Tools' CMake file for Greenstone
+# where we want to build static xpdf-tools executables.
+# Refer to the GS-README.txt file for the Greenstone "xpdf-tools"
+# gs2-extension and read section D for the GS specific customisations
+# in this file and the reasoning behind them, most of which have to do
+# with attempting to successfully build xpdf-tools statically.
 #========================================================================
 
@@ -21,8 +25,6 @@
 
 
-# For Mac OSX, when -static is passed in for linking, we end up with the error "ld: library not found for -lcrt0.o"
-# See https://stackoverflow.com/questions/3801011/ld-library-not-found-for-lcrt0-o-on-osx-10-6-with-gcc-clang-static-flag
-# On Mac OSX, compile it with -Bstatic, as per https://stackoverflow.com/questions/844819/how-to-static-link-on-os-x
-# XPDFTOOLS.sh will have set the GSDLFLAG_STATIC to either "-static" (for linux) or "-Bstatic" for darwin
+# When compiling statically, XPDFTOOLS.sh will have set the custom
+# GSDLFLAG_STATIC flag to either "-static" for linux or "-Bstatic" for darwin
 
 if(GSDLFLAG_STATIC)
@@ -131,23 +133,4 @@
 endif ()
 
-# We want to build static xpdf-tools binaries. See
-# https://stackoverflow.com/questions/24648357/compiling-a-static-executable-with-cmake
-# Want to make the min number of changes for building statically, so using the way
-# below. Beware, must *append* "-static" to existing CMAKE_EXE_LINKER_FLAGS=LD_FLAGS
-##SET(CMAKE_FIND_LIBRARY_SUFFIXES ".a")
-##SET(BUILD_SHARED_LIBS OFF)
-##SET(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -static")
-
-# The original, unmodified CMakeLists.txt was not set up sufficiently
-# for static compilation of xpdf-tools. As a result, compile would first fail
-# with errors about undefined refs to mutex / lpthread.
-# When building xpdf-tools statically, need to add the following 2 lines as well
-# as append "Threads::Threads" to the end of each "target_link_libraries(<list>)"
-# See https://stackoverflow.com/questions/1620918/cmake-and-libpthread
-# found googling cmake and "-lpthread" (pthread) after ERRORS to do with this, like:
-#   undefined reference to `pthread_mutex_unlock'
-##set(THREADS_PREFER_PTHREAD_FLAG ON)
-##find_package(Threads REQUIRED)
-
 #--- pdftops
 
@@ -222,25 +205,4 @@
                           ${LCMS_LIBRARY} ${PNG_LIBRARIES})
   endif ()
-# Doing the regular target_link_libraries() in static mode results in building with 
-# "-Wl,-Bstatic -lfreetype -lpng15 -lz -Wl,-Bdynamic -lpthread" at end of link line
-# and produces broken binaries for pdftohtml/pdftoppm/pdftops/pdftopng.
-# Note that PNG_LIBRARIES includes zlib/lz: "-lpng -lz", and along with freetype,
-# these are linked statically. However, Threads/lpthread is included as a dynamically
-# linked library instead of including a .a (regardless of whether it's appended
-# as -lpthread or Threads::Threads in else above), contributing to the pdfhtml binary
-# produced being a partially static, partially dynamic one,
-# so a dynamic executable overall.
-# The order of dynamic .so files listed by ldd in the broken binary differs from
-# a manually linked working version of pdftohtml, and seems to be the only difference
-# between the two in ldd output. Not using "-Wl,-Bstatic" and using -static (-Bstatic on Mac)
-# in its place creates a partially static dynamic executable that isn't broken, whereas
-# additionally removing "-Wl,-Bdynamic -lpthread" and replacing it with -lpthread
-# moreover produces a working pdftohtml that is a fully static linked executable.
-# The inclusion of the math lib and c lib (lm and lc) in the final link command
-# are to completely bypass the remaining .so dependencies that were present in
-# the executable and produce the fully static executable.
-# Not sure what colormanager (lcms) and typelibrary, or how they're written in -l
-# form as they were not present when the original unmodified static linking command
-# was run, so they've not been included in the replacement static linking command. 
   install(TARGETS pdftohtml RUNTIME DESTINATION bin)
   install(FILES ${PROJECT_SOURCE_DIR}/doc/pdftohtml.1 DESTINATION man/man1)
