First attempt at completing the Win32 docs.

git-svn-id: svn://svn.lyx.org/lyx/lyx-devel/branches/BRANCH_1_3_X@10187 a592a061-630c-0410-9148-cb99ea01b6c8

INSTALL.Win32

@@ -0,0 +1,141 @@
+=================
+INSTALL for Win32
+=================
+
+Building LyX the first time can appear to be a daunting task, but much of
+that is knowing which packages to download in the first place.
+
+The instructions below should guide you through the installation of
+the MinGW/MinSYS build environment, together with details on how to
+grab and build the Qt toolkit and how to grab Aspell and LyX.
+
+Once you've done all that, you should go read the README in
+development/Win32/packaging/ The two scripts in the same directory,
+build_lyxwin.sh and package_lyxwin.sh should automate the entire
+build process. If not and you really can't figure out what to do next,
+then please, please drop a mail to lyx-devel@lists.lyx.org.
+
+Enjoy!
+The LyX Team
+
+=============================================================================
+1 MinGW & MSYS
+
+1.1 Download the following packages from http://www.mingw.org/download.shtml:
+
+      MinGW-3.2.0-rc-3.exe
+      binutils-2.15.94-20050118-1.tar.gz
+      MSYS-1.0.11-2004.04.30-1.exe
+      msysDTK-1.0.1.exe
+
+1.2 Install MinGW-3.2.0-rc-3.exe in C:\MinGW
+
+1.3 Install MSYS-1.0.11-2004.04.30-1.exe in C:\msys
+
+1.4 Install msysDTK-1.0.1 in C:\msys
+
+1.5 Extract binutils-2.15.94-20050118-1.tar.gz in C:\MinGW
+    (i.e., overwrite the existing binutils)
+
+
+2. Gettext & Libiconv
+
+2.1 Download the following packages from
+    http://www.gnu.org/software/gettext/gettext.html:
+
+      gettext-tools-0.13.1.bin.woe32.zip
+      gettext-runtime-0.13.1.bin.woe32.zip
+      libiconv-1.9.1.bin.woe32.zip
+
+2.2 Extract the three packages in C:\MinGW
+
+
+
+3 QT/Win Free Edition
+  http://qtwin.sourceforge.net/index.php/QT/Free_from_CVS_with_Mingw
+
+3.1 Get the latest CVS version
+
+    Using the cvs executable that is packaged with MinSYS,
+    from the MinSYS command prompt:
+
+    $ cd ~
+    $ cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/kde-cygwin login
+      <return> (no password)
+    $ cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/kde-cygwin co \
+         -r QT_WIN32_3_3_BRANCH -d qt3 qt-3
+
+    Alternatively, use the TortoiseCVS graphical interface.
+
+3.2 Compile the QT library
+
+    Create two .bat files, in the top-level directory of the Qt tree,
+    my_configure.bat and my_make.bat. Mine are shown below. Obviously,
+    you'll have to tweak them ;-)
+
+    $ cat my_configure.bat
+    set QTDIR=J:\MinSys\home\Angus\qt3
+    set MINGW=J:\MinGW
+    set PATH=J:\MinSys\home\Angus\qt3\bin;J:\MinGW\bin;C:\WINDOWS\system32;C:\WINDOWS
+    set QMAKESPEC=win32-g++
+    configure.bat -verbose
+
+    $ cat my_make.bat
+    set QTDIR=J:\MinSys\home\Angus\qt3
+    set MINGW=J:\MinGW
+    set PATH=J:\MinSys\home\Angus\qt3\bin;J:\MinGW\bin;C:\WINDOWS\system32;C:\WINDOWS
+    set QMAKESPEC=win32-g++
+    mingw32-make symlinks
+    mingw32-make src-moc
+    mingw32-make sub-src
+
+    The first time that you build the Qt sources, run my_configure.bat.
+    Thereafter, you should be able to get away with my_make.bat. If it fails,
+    you should try my_configure.bat again, but this will overwrite all the
+    Qt header files, so you'll end up rebuilding large chunks of LyX as well.
+
+    $ cmd.exe
+    PROMPT> my_configure.bat
+
+4. Aspell
+
+4.1 Download aspell-0.50.5.tar.gz from ftp://ftp.gnu.org/gnu/aspell/
+    (note: version 0.60.2 does not compile)
+    Download dictionaries from ftp://ftp.gnu.org/gnu/aspell/dict/
+    Eg: en/aspell-en-0.50-2.tar.bz2
+        de/aspell-de-0.50-2.tar.bz2
+
+4.2 Extract all files in your MSYS home directory. From the
+    MinSYS command prompt:
+
+    $ gunzip aspell-0.50.5.tar.gz
+    $ bunzip2 aspell-en-0.50-2.tar.bz2
+    $ tar xvf aspell-0.50.5.tar
+    $ tar xvf aspell-en-0.50-2.tar
+    $ rm -f aspell-0.50.5.tar
+    $ rm -f aspell-en-0.50-2.tar
+
+    There's no need to build Aspell now. The script in
+    development/Win32/packaging should do it for you.
+
+5. LyX
+
+5.1 Get the latest CVS version
+
+    Using the cvs executable that is packaged with MinSYS,
+    from the MinSYS command prompt:
+
+    $ cd ~
+    $ mkdir lyx && cd lyx
+    $ cvs -d:pserver:anoncvs@anoncvs.us.lyx.org:/cvs/lyx login
+      (The password is "lyx" (no inverted commas))
+    $ cvs -d:pserver:anoncvs@anoncvs.us.lyx.org:/cvs/lyx \
+          checkout -r BRANCH_1_3_X -d 13x lyx-devel
+
+    Alternatively, use the TortoiseCVS graphical interface.
+
+    There's no need to build LyX now. The script in
+    development/Win32/packaging should do it for you.
+
+Now go read the README in development/Win32/packaging.
+=============================================================================

README.Win32

@@ -1,39 +1,36 @@
-================================================================
+================
-README for Win32 by Ruurd Reitsma (R.A.Reitsma@wbmt.tudelft.nl)
+README for Win32
-================================================================
+================
 
-Lyx has been ported to Win32 using the Cygwin environement. The port
+LyX has been ported to Win32 using the Cygwin environement.
-consists of a few small tweaks to deal with DOS-style pathnames, so
+See README.Cygwin for details.
-LyX can use Win32 TeX distros like fptex and MiKTeX. There's also a
-cygwin TeTeX port, but the native Win32 ports have a definite speed
-advantage. Besides that, nothing fancy.
 
-The prerequisites are (obviously?):
+Ever since Ruurd Reitsma made his port of LyX 1.3.3 to Windows
+available to the general public in 2003, users of LyX/Win have had to
+fight to overcome bugs that simply weren't present on other
+platforms. Ruurd did a superb job in writing the original port, but
+didn't have the resources to squash all the irritating little bugs
+discovered by many people using LyX "for real". 
 
-* cygwin installation (http://www.cygwin.com/).
+The official LyX line on these LyX/Win ports has always been that
-* decent X server; eXceed, X-Win32, or maybe even Cygwin/XFree86.
+it's nice to know they exist but we won't support them
-* working TeX installation; fpTex, MikTex.
+officially. There were two reasons for this: we didn't have the
+necessary knowledge or resources and, until recently, only
+closed-source versions of the Qt GUI library existed. The increasing
+maturity of the Qt/Win Free project means that this latter point is
+no longer true, so we felt that we should make the effort and make
+LyX/Win an official part of LyX.
 
-It should compile out of the box, but there might be some libraries
+As a result, LyX 1.3.6 cannot really be classified as a minor bug fix
-missing in the final link step. You'll have to add them to the Makefile
+release, especially for Windows users. Large chunks of the code base
-by hand. Be sure to include -lregex, because cygwin's builtin regex is
+have been touched in an attempt to resolve those problems that
-sortof weird (filedialogs will turn up empty...)
+Windows users have found with Ruurd's original ports. We feel
+confident that LyX 1.3.6 will be the best ever version of LyX on
+Windows. We are not confident, however, that we haven't introduced
+any new bugs.
 
-If you want to run lyx with no console windows open, there's a small
+Detailed installation instructions can be found in INSTALL.Win32 for
-program in development/Win32 that will set the proper environment vars
+those who wish to compile LyX for themselves. For the rest of us,
-and start lyx.
+LyX/Win comes with its own installer, so installation should be pretty
-
+straightforward. As always, more detailed help can be found on the
-Compile with:
+wiki at http://wiki.lyx.org/Windows.
-
-gcc lyxwin32.C -O2 -o lyxwin32 -static -Wall -Wno-format \
--Wstrict-prototypes -Wmissing-prototypes -mwindows -e _mainCRTStartup
-
-Also make sure the latex binaries are in your Windows path. Windvi and
-Yap are auto detected, and you might want to make a symlink to Adobe
-Acrobat so it's detected too:
-
-ln -s //c/Program\ Files/adobe/Acrobat\ 4.0/Reader/AcroRd32.exe \
-/usr/bin/acroread
-
-Many thanks to Steven van Dijk, Claus Hentschel and Miyata Shigeru for
-starting the porting business.

development/Win32/packaging/README

@@ -1,12 +1,19 @@
 Packaging LyX 1.3.6 for Windows
 ===============================
+Angus Leeming, 14 July 2005
+===========================
 
 Preparing the way
 =================
 
 The very first thing to do on the way to creating a LyX/Win package is
-to build the sources and install them somewhere accessible. (I've been
+to build the sources and install them somewhere accessible. I've written
-using PREFIX='/J/Programs/LyX'.)
+a script, build_lyxwin.sh, that performs all the necessary steps. Please
+read the preamble and (un)comment those steps that are necessary at the
+end of the script.
+
+The (eventual --- mingw is a *very* slow compiler) result is a lyx
+package that's almost ready to go in $LYX_SRCS/build/installprefix.
 
 Thereafter, the contents of this tree must be manipulated a
 little. I've written a little script, package_lyxwin.sh, to automate

development/Win32/packaging/build_lyxwin.sh

@@ -0,0 +1,319 @@
+#! /bin/sh
+
+# This script aims to do averything necessary to automate the building
+# of a LyX/Win package.
+
+# Invocation:
+# sh build_lyxwin.sh "1.3.6-pre23"
+# The string will be shown in the "About LyX" dialog.
+
+# This script is written as a bunch of subroutines. You'll probably
+# only need to build a couple of the packages (dtl, aspell) once.
+# Thereafter, the invocation of these subroutines can be commented out.
+# (See the end of the script.)
+
+# Notes:
+# It uses the MinGW/MinSYS environment and compiler.
+
+# It asks whether the Qt and LyX cvs trees are up to date.
+# It asks whether the Qt library has been compiled.
+# It checks that qt-mt3.dll, libiconv-2.dll,
+#   mingw10.dll and clean_dvi.py exist.
+# It compiles the dv2dt and dt2dv utilites.
+# It compiles and installs the Aspell library.
+# It compiles and installs LyX.
+# It copies the dv2dt and dt2dv utilites, the .dlls and
+#   clean_dvi.py to the lyx package.
+# It modifies the Resources/lyx/configure script to
+#   ensure that the generated .dvi file is usable.
+
+# Once all this is done, you're ready to "package" LyX.
+# See the README for details.
+
+# The script compiles the .dll version of the Qt libraries. Linking of lyx
+# against this will, therefore, take "some time".
+
+# It compiles the static version of the Aspell libraries because no
+# .dll version exists.
+
+HOME="/home/Angus"
+
+# You may need to change these three variables.
+QT_DIR="${HOME}"/qt3
+ASPELL_DIR="${HOME}"/aspell-0.50.5
+# A space-separated string of directories
+# ASPELL_DICT_DIRS="${HOME}/aspell-en-0.50-2 ${HOME}/aspell-de-0.50-2 "
+ASPELL_DICT_DIRS="${HOME}/aspell-en-0.50-2"
+LYX_DIR="${HOME}"/lyx/13x
+
+# Everything from here on down should be OK "as is".
+PACKAGING_DIR="$LYX_DIR/development/Win32/packaging"
+DTL_DIR="$PACKAGING_DIR/dtl"
+CLEAN_DVI_DIR="$PACKAGING_DIR"
+
+ASPELL_INSTALL_DIR="c:/Aspell"
+LYX_ASPELL_DIR="/c/Aspell" # the Autotools don't like "C:/" syntax.
+LYX_RELATIVE_BUILDDIR=build
+LYX_INSTALL_DIR=installprefix
+
+# These are all installed in the final LyX package
+QT_DLL="${QT_DIR}/bin/qt-mt3.dll"
+LIBICONV_DLL="/j/MinGW/bin/libiconv-2.dll"
+MINGW_DLL="/j/MinGW/bin/mingwm10.dll"
+
+DT2DV="$DTL_DIR/dt2dv.exe"
+DV2DT="$DTL_DIR/dv2dt.exe"
+CLEAN_DVI_PY="$CLEAN_DVI_DIR/clean_dvi.py"
+
+# Change this to 'mv -f' when you are confident that
+# the various sed scripts are working correctly.
+MV='mv -f'
+
+check_dirs_exist()
+{
+    for dir in "$QT_DIR" "$ASPELL_DIR" "$LYX_DIR" "$DTL_DIR"
+    do
+      test -d "$dir" || {
+	  echo "$dir does not exist" >&2
+	  exit 1
+      }
+    done
+}
+
+
+query_qt()
+{
+    echo "Please ensure that the Qt and LyX cvs trees are up to date"
+    echo "and that the Qt library is compiled and ready to go."
+    echo "Press any key to continue"
+    read ans
+}
+
+
+check_files_exist()
+{
+    # Check that the dlls and clean_dvi.py exist
+    for file in "${QT_DLL}" "${LIBICONV_DLL}" "${MINGW_DLL}" "${CLEAN_DVI_PY}"
+    do
+      test -r "${file}" || {
+	  echo "$file does not exist" >&2
+	  exit 1
+      }
+    done
+}
+
+
+build_dtl()
+{
+    # dt2dv and dv2dt
+    (
+	cd "$DTL_DIR" || {
+	    echo "Unable to cd $DTL_DIR" >&2
+	    exit 1
+	}
+
+	make || {
+	    echo "Failed to make $DTL_DIR" >&2
+	    exit 1
+	}
+    )
+
+    for file in "${DT2DV}" "${DV2DT}"
+    do
+      test -x "$file" || {
+	  echo "${file} does not exist or is not executable" >&2
+	  exit 1
+      }
+    done
+}
+
+
+build_aspell()
+{
+    # Aspell
+    (
+	cd "$ASPELL_DIR" || {
+	    echo "Unable to cd $ASPELL_DIR" >&2
+	    exit 1
+	}
+
+	./configure --enable-static --disable-shared --prefix="${ASPELL_INSTALL_DIR}" --sysconfdir="${ASPELL_INSTALL_DIR}" --enable-docdir="${ASPELL_INSTALL_DIR}/doc" --datadir="${ASPELL_INSTALL_DIR}/data" --enable-pkgdatadir="${ASPELL_INSTALL_DIR}/data" --enable-dict-dir="${ASPELL_INSTALL_DIR}/dict" --enable-win32-relocatable || {
+	    echo "Failed to configure $ASPELL_DIR" >&2
+	    exit 1
+	}
+
+        # We have to clean up two of the generated Makefiles.
+	TMP=tmp.$$
+	MAKEFILE=examples/Makefile
+	sed '
+# Replace "CC = gcc" with "CC = g++"
+s/^ *\(CC *= *\)gcc *$/\1g++/
+# Remove trailing "/" from the -I directory.
+s@^ *\(INCLUDES *= *-I\${top_srcdir}/interfaces/cc\)/ *$@\1@
+' "${MAKEFILE}" > "${TMP}"
+	cmp -s "${MAKEFILE}" "${TMP}" && {
+	    echo "${MAKEFILE} is unchanged" 2>&1
+	} || {
+	    diff -u "${MAKEFILE}" "${TMP}"
+	    ${MV} "${TMP}" "${MAKEFILE}"
+	}
+	rm -f "${TMP}"
+
+	MAKEFILE=prog/Makefile
+	sed '
+# Remove trailing "/" from the -I directories.
+/^ *INCLUDES *= *-I\${top_srcdir}\/common/{
+:loop
+$!{
+N
+/\n *$/!bloop
+}
+s@/ *\(\\ *\n\)@ \1@g
+}' "${MAKEFILE}" > "${TMP}"
+	cmp -s "${MAKEFILE}" "${TMP}" && {
+	    echo "${MAKEFILE} is unchanged" 2>&1
+	} || {
+	    diff -u "${MAKEFILE}" "${TMP}"
+	    ${MV} "${TMP}" "${MAKEFILE}"
+	}
+	rm -f "${TMP}"
+
+	make || {
+	    echo "Failed to make $ASPELL_DIR" >&2
+	    exit 1
+	}
+
+	rm -fr "$ASPELL_INSTALL_DIR" || {
+	    echo "Failed to remove $ASPELL_INSTALL_DIR prior to installing Aspell" >&2
+	    exit 1
+	}
+
+	make install || {
+	    echo "Failed to install $ASPELL_DIR" >&2
+	    exit 1
+	}
+    )
+}
+
+
+build_aspell_dicts()
+{
+    (
+	PATH="${LYX_ASPELL_DIR}:$PATH"
+	export PATH
+
+	for dir in $ASPELL_DICT_DIRS
+	do
+	  (
+		cd $dir
+		./configure
+		make
+		make install
+	  )
+	done
+    )
+
+}
+
+modify_version_C()
+{
+	VERSION_C="src/version.C"
+	test -r "${VERSION_C}" || {
+	    echo "Unable to find ${VERSION_C}"
+	    return
+	}
+	test "${LYX_VERSION_STR}" == "" && return
+
+	sed '/char const \* lyx_version = /s/"[^"]*"/"'${LYX_VERSION_STR}'"/' \
+	    ${VERSION_C} > tmp.$$
+	diff -u ${VERSION_C} tmp.$$
+	${MV} tmp.$$ ${VERSION_C}
+}
+
+
+build_lyx()
+{
+    (
+	cd "${LYX_DIR}" || {
+	    echo "Unable to cd ${LYX_DIR}" >&2
+	    exit 1
+	}
+
+	# Check the line endings of configure.ac
+	# The configure script will be unable to create config.h if it
+	# contains Win32-style line endings.
+	sed 's/
+$//' ${LYX_DIR}/configure.ac > configure.ac.$$
+	cmp -s ${LYX_DIR}/configure.ac configure.ac.$$ && {
+	    rm -f configure.ac.$$
+	} || {
+	    mv -f configure.ac.$$ ${LYX_DIR}/configure.ac
+	    echo 'configure.ac has Win32-style line endings. Corrected' >&2
+	}
+
+	./autogen.sh || {
+	    echo "autogen.sh failed" >&2
+	    exit 1
+	}
+
+	BUILDDIR="${LYX_RELATIVE_BUILDDIR}"
+	test ! -d "${BUILDDIR}" && {
+	    mkdir "${BUILDDIR}" || \
+		Error "Unable to create build dir, ${BUILDDIR}."
+	}
+
+	CONFIGURE="../configure --without-x --with-included-gettext --with-extra-prefix='${LYX_ASPELL_DIR}' --with-frontend=qt QTDIR='$QT_DIR'"
+
+	echo "${CONFIGURE}"
+	cd "${BUILDDIR}"
+	echo "${PWD}"
+	eval "${CONFIGURE}" || {
+	    echo "Failed to configure LyX" >&2
+	    exit 1
+	}
+
+	# Modify the "lyx_version" string in build/src/version.C
+	modify_version_C
+
+	# Build LyX
+	make || {
+	    echo "Failed to make $LYX_DIR" >&2
+	    exit 1
+	}
+    )
+}
+
+
+install_lyx()
+{
+    (
+	BUILDDIR="${LYX_RELATIVE_BUILDDIR}"
+	cd "${LYX_DIR}/${BUILDDIR}" || {
+	    echo "Unable to cd ${LYX_DIR}/${BUILDDIR}" >&2
+	    exit 1
+	}
+
+	rm -fr "$LYX_INSTALL_DIR" || {
+	    echo "Failed to remove $LYX_INSTALL_DIR prior to installing LyX" >&2
+	    exit 1
+	}
+
+	make install || {
+	    echo "Failed to install $LYX_DIR" >&2
+	    exit 1
+	}
+    )
+}
+
+LYX_VERSION_STR=""
+test $# -ne 0 && LYX_VERSION_STR=$1
+
+check_dirs_exist || exit 1
+query_qt || exit 1
+check_files_exist || exit 1
+#build_dtl || exit 1
+#build_aspell || exit 1
+#build_aspell_dicts || exit 1
+build_lyx || exit 1
+install_lyx || exit 1
+# The end