LyX/Cygwin 1.5.7
----------------

This package provides LyX version 1.5.7 built as a Cygwin application.
Thus, a preliminary requirement is the installation of the Cygwin runtime.
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

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 your home directory (if you don't have the HOME variable
already set in your Windows environment) and the language to be used
in the GUI. These are the only changes that you need to do.
Please, note that you have to use a cygwin editor for editing /etc/lyxprofile,
as a native Windows editor may introduce wrong line endings, causing troubles
with the bash shell.

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->Outputs->Paths 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 wait for the official release
of LyX Qt/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 search
------------------

Reverse DVI 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) in the previewed DVI file.
This feature can be enabled as follows:

  * Activate src-specials by changing the "LaTeX (plain)->DraftDVI" converter
    in Tools->Preferences->Converters to "latex --src $$i" if you use tetex,
    or to "latex -src-specials $$i" if you use miktex.
    As an alternative to redefining the converter (maybe because you use
    pplatex instead of latex for producing a DraftDVI), you can insert
    "\usepackage[active]{srcltx}" in the preamble of the LyX file.

  * A program or script will be called by the dvi viewer when initiating
    a reverse dvi search (xdvi uses Ctrl-click, yap uses 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 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
    installation, you will find its source in the /usr/local/share/lyx/etc
    directory). 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 did no mistakes, and if src-specials are activated as previously
    described, whenever you Ctrl-click in xdvi, or double click in yap, 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, November 2008

