LyX/Cygwin 1.6.6
----------------

This package provides LyX version 1.6.6 built as a Cygwin application.
Thus, a preliminary requirement is the installation of the Cygwin runtime.
Note that you need Cygwin 1.7.0 or later, as previous versions will not work.
Before installing LyX, you should install at least the following Cygwin
packages (and all other packages pulled in by dependencies):

aspell         ghostscript
python         tetex-extra
gettext        ImageMagick
libpng
libstdc++6

However, you must be aware that the ImageMagick package has a dependency
on X11, so installing it would also pull in the Cygwin/X server. This
version of LyX does not need a X server, and if you want to avoid it, you
can simply install the native Windows version of ImageMagick from
http://www.imagemagick.org/script/binary-releases.php#windows

You also have the option of installing native versions of ghostscript
and latex, such that you could skip the installation of the cygwin
packages listed in the second column above.

After installing the required packages, you will find instructions
on how to install LyX/Cygwin in the file INSTALL.txt.

This package contains both a wrapper for launching LyX from the Windows GUI
(in order to set up a proper environment for LyX and avoid having a terminal
window open) and a real binary for command line usage.

lyx-win.exe      wrapper, to be used from the Windows GUI
lyx-qtwin.exe    real binary, to be used from the command line

When using the command line, you can also launch LyX by simply typing lyx,
as this is a symlink to lyx-qtwin.exe (make sure that /usr/local/bin is in
your PATH).

After installation, you may wish to edit the file /etc/lyxprofile in order
to specify the language to be used in the GUI. Your home directory should be
guessed by /etc/lyxprofile but it is better that you set the HOME variable in
your Windows environment. You can also create a file named .lyxprofile in your
home directory if you want to override the settings in /etc/lyxprofile.
These are the only changes that you need to do. Please, note that you have to
use a cygwin editor for editing /etc/lyxprofile or ~/.lyxprofile, as a native
Windows editor may introduce wrong line endings, causing troubles with the
bash shell. Also note that /etc/lyxprofile has been improved, but your old
copy will not be touched. So, you are responsible for upgrading it using the
new version that you find at /usr/local/share/lyx/etc/lyxprofile.

In /usr/local/share/lyx/etc/lyx.reg you will find registry entries for
associating a .lyx file to lyx-win.exe. Simply navigate to that dir using
the Windows explorer, select the file and choose "Join" or whatever the name
of that entry in your locale. An easy way for opening an explorer window in
the right location when working in a cygwin shell, is using the command
"cygstart /usr/local/share/lyx/etc".


Caveat
------

Under Tools->Preferences->Output->LaTeX you will find a checkbox labeled
"Use Windows-style paths in LaTeX files". Its status (checked or unchecked)
is determined at configure time. If you use MikTeX you'll find that it is
checked, whereas if you use the cygwin tetex you'll find that it is unchecked.
Please, don't play with this checkbox if you don't know what you are doing.


Upgrading from previous versions
--------------------------------

This should be straightforward and you need to do nothing. During the
upgrade, the file /etc/lyxprofile will not be replaced, as you may have
customized it. However, be aware that some old variables are no longer
supported (see below), but they are not harmful if left in place. If you
experience problems such as disappearing entries from the View menu, this
means that you are upgrading from 1.4 and customized some formats. In this
case open the preferences dialog, go to the "File formats" section and check
the "Document format" checkbox for each format that you would like to see in
the View menu. If you still experience some weird problem, try moving away
the ~/.lyx/preferences file by renaming it and see whether this solves it.
If you have custom layout files using non-ascii characters, you should
convert them to utf8. Please read the UPGRADING.txt file for details.

Starting from version 1.4.3, an official cygwin version of LyX is also
available with package name "lyx", so I had to change the package name
to "LyXwin" in order to avoid conflicts. This means that if you are
upgrading from 1.4.3 or earlier of this package (and not have the official
version installed) the old version is not recognized as such and thus it is
not automatically uninstalled. So, you have to uninstall it first, and then
perform a new installation as described in the file INSTALL.txt.

Starting from version 1.5.0, the old xforms frontend is no more available,
so if you want a X11 version, you'll have to either compile it by yourself
or wait for the official release of LyX Qt4/X11, which you can install in
parallel to this one without conflicts, though.

The old environment variable LYX_WINPATHS used in the 1.4.x versions is no
longer supported, so if you use Windows applications that do not understand
posix paths you need to call them through a wrapper script in order to
translate the paths to the native Windows style.

You can find a wrapper script skeleton in /usr/local/share/lyx/etc/wrapper.sh.
Simply give it the same name of your Windows application (without any
extension), and then place it in /usr/local/bin. Now edit it using a cygwin
text editor and change command_name in the last line with the full path
to the Windows application with the same name. That's it.
The wrapper should work with the vast majority of applications.


Reverse DVI/PDF search
----------------------

Reverse search allows the cursor in LyX to automatically jump to the point
corresponding to where you Ctrl-click (if using xdvi) or double click
(if using yap or SumatraPDF) in the previewed DVI or PDF file.
This feature can be enabled as follows:

  * For enabling reverse DVI search, change the "LaTeX (plain)->DraftDVI"
    converter in Tools->Preferences->File Handling->Converters to
    "latex -src-specials $$i". As an alternative to redefining the converter
    (maybe because you use pplatex instead of latex for producing a DraftDVI),
    insert "\usepackage[active]{srcltx}" in the preamble of the LyX file.

  * For enabling reverse PDF search, you have to insert "\usepackage{pdfsync}"
    in the preamble. Note that only SumatraPDF supports reverse PDF search,
    currently. In order to allow both DVI and PDF reverse search, you can
    also insert in the preamble the following lines:
       \usepackage{ifpdf}
       \ifpdf
         \usepackage{pdfsync}
       \else
         \usepackage[active]{srcltx}
       \fi
    In this way, you can preview the file as either DVI or PDF (pdflatex)
    and the right package will be used.

  * A program or script will be called by the dvi/pdf viewer when initiating a
    reverse search (xdvi uses Ctrl-click, yap and SumatraPDF use double click).
    This program should take 2 arguments, a filename and a line number, and
    should pass this info to a running instance of LyX. This can be done
    either using the lyxpipe (set by default to ~/.lyx/lyxpipe) or the
    unix domain socket that lyx creates in its temporary directory.
    A suitable script (/usr/local/bin/lyxeditor.sh) is already included in
    this package for using the lyxpipe machinery. You could modify it in order
    to better fit your needs, but it should already work out of the box.
    Alternatively, you can use lyxclient.exe for communicating with lyx
    through the socket mechanism.

  * If you use xdvi, you don't need to do anything else, as lyx already
    provides the necessary hooks for automatically using lyxclient.exe.
    However, if for whatever reason you want to use the lyxpipe instead
    of the socket for communicating with lyx, simply change the DVI
    viewer in "Tools->Preferences->File Handling->File formats" to
    "xdvi -editor 'lyxeditor.sh %f %l'" (without double quotes), where
    lyxeditor.sh is the aforementioned script.

  * If you use yap, you should set the name of the program directly in yap
    through the View->Options menu. However, as yap is a native Windows
    application, both lyxeditor.sh and lyxclient.exe have to be launched
    through the wrapper program /usr/local/bin/lyxeditor.exe.
    After launching yap, choose the View->Options menu and select
    the "Inverse DVI Search" tab. Click on the "New..." button and, in the
    window which opens, enter "LyX Editor" (or any other name you like) in
    the "Name:" field. Now click on the button labeled "..." to open a
    filedialog and navigate to the directory containing lyxeditor.exe (it
    will be C:\cygwin\usr\local\bin if C:\cygwin is your root directory).
    Select lyxeditor.exe and then specify the program arguments as "%f %l"
    (without the double quotes) if you want to use the lyxpipe, or as
    "-g %f %l" (again, without quotes) if you want to use the lyxsocket.

  * If you use SumatraPDF, you should launch it through a wrapper script.
    In Tools->Preferences->File Handling->File formats->PDF (pdflatex)
    specify SumatraPDF.sh as the viewer, where SumatraPDF.sh is the
    following shell script:
      #!/bin/bash
      cd $(dirname $1)
      SumatraPDF.exe -inverse-search "lyxeditor.exe -g \"%f\" %l" $(basename $1)
    best placed in /usr/local/bin (remember to make it executable by
    "chmod 755 /usr/local/bin/SumatraPDF.sh" and be sure that SumatraPDF.exe
    is in your command path, or use its absolute path in the script).
    The -g option enables communication via the lyxsocket (recommended); omit
    it if you want to use the lyxpipe.

  * If you did no mistakes, and if src-specials are activated as previously
    described, whenever you Ctrl-click in xdvi, or double click in yap or
    SumatraPDF, the cursor in LyX should jump to the desired location.


Disclaimer
----------

This package works for me but I cannot guarantee that it does for you, or
even that using it your computer will not blow in smoke ;-)

-- 
Enrico Forestieri, May 2010

