listerrors.lyx : Update a link.

[lyx.git] / UPGRADING

diff --git a/UPGRADING b/UPGRADING
index dc5d43224212a15226525345c2d01f88bf0dcb8a..74bb0127da12dd110345ecba121037e595484f1c 100644 (file)
--- a/UPGRADING
+++ b/UPGRADING
@@ -1,6 +1,27 @@
-How do I upgrade my existing LyX system to version 1.6.x?
+How do I upgrade my existing LyX system to version 2.1.x?

 ---------------------------------------------------------
 
 ---------------------------------------------------------
 

+* Upgrading from LyX 2.0.x:
+
+Python version >=2.4 is now required.
+
+Python version >3.0 is still not yet supported.
+
+* Upgrading from LyX 1.6.x:
+
+The format of preference and session files has changed. LyX 2.0.x is
+able to read old files but will save them in the new format.
+
+The format of layout files has changed but, as before, layout2layout.py
+will convert older versions to the new format automatically.
+
+The syntax of the languages file has been changed. If you use a
+modified languages file, you will need to adapt it to the new syntax.
+
+There has been a large change in how Flex insets are named.
+When exporting back to 1.6.x format user-defined flex insets will not
+be properly reverted. See RELEASE-NOTES for details.
+

 * Upgrading from LyX 1.5.x:
 
 The format of preference and session files has changed. LyX 1.6.x is
 * Upgrading from LyX 1.5.x:
 
 The format of preference and session files has changed. LyX 1.6.x is


@@ -82,44 +103,70 @@ have to update them
 Build requirements
 ------------------
 
 Build requirements
 ------------------
 

-LyX 1.6 uses the Qt 4.x toolkit (version 4.2.0 or newer). Contrary to
-previous versions of LyX, it won't build against Qt 2.x or 3.x.
-Furthermore, the XForms frontend was dropped.
+LyX 2.0 uses the Qt 4.x toolkit (see INSTALL file).

 
 

-LyX's graphics handling system has changed substantially. If you
-do not have the JPEG library installed, you may need to install
-it before you can use the graphics capabilities of LyX. If you
-do not have the ImageMagick command-line tools installed, you
-will need to modify the default set up of LyX, or install them,
-in order to get previews of your document's graphics.
+If you do not have the JPEG library installed, you may need to install it
+before you can use the graphics capabilities of LyX. If you do not have the
+ImageMagick command-line tools installed, you will need to modify the default
+set up of LyX, or install them, in order to get previews of your document's
+graphics.

 
 Document transfer
 -----------------
 
 * Compatibility with older documents/layouts
 
 
 Document transfer
 -----------------
 
 * Compatibility with older documents/layouts
 

-LyX 1.6.x uses an external python script, lyx2lyx, to import documents
+LyX 2.0.x uses an external python script, lyx2lyx, to import documents

 written using previous versions of LyX. All versions of LyX as far back as
 written using previous versions of LyX. All versions of LyX as far back as

-0.10 are supported, so any klyx users still holding out for an alternative
-to xforms will finally be able to put their dinosaur to rest ;-)
-
-Of course, this means that you must have python (at least version 2.3.4)
-installed in order to use LyX 1.6.x with your old documents.
-
-lyx2lyx also has the framework in place to be able to convert
-documents to an earlier format (which requires python 2.3.4 at
-least). However, these converters have only been written for the
-conversion from 1.6.x to 1.5.x, 1.4.x and 1.3.x, so versions of LyX
-older than 1.3.0 will NOT be able to read documents saved with LyX
-1.6.x. The conversion from 1.6.x to 1.5.x-1.3.x is lossless as long as
-no new features are used. lyx2lyx tries hard to find something
-equivalent for new features such as boxes, but this is known to fail
-sometimes. LyX 1.5.7 contains an updated lyx2lyx that can read
-documents in 1.6.x format.
+0.10 are supported.
+
+Of course, this means that you must have python (>= 2.3.4, <3)
+installed in order to use LyX 2.0.x with your old documents.
+
+lyx2lyx also has the framework in place to be able to convert documents to an
+earlier format (which requires python 2.3.4 at least). However, these
+converters have only been written for the conversion from 2.0.x to 1.6.x,
+1.5.x, 1.4.x and 1.3.x, so versions of LyX older than 1.3.0 will NOT be able to
+read documents saved with LyX 2.0.x. The conversion from 2.0.x to 1.6.x-1.3.x
+is lossless as long as no new features are used. lyx2lyx tries hard to find
+something equivalent for new features such as boxes, but this is known to fail
+sometimes. LyX 1.6.9 contains an updated lyx2lyx that can read documents in
+2.0.x format.

 
 Furthermore, LyX uses a converter layout2layout.py, also written in python
 that will convert old layout files on the fly. You can also call it manually
 
 Furthermore, LyX uses a converter layout2layout.py, also written in python
 that will convert old layout files on the fly. You can also call it manually

-on your layout files if you want to convert them to 1.6.x format permanently.
+on your layout files if you want to convert them to 2.0.x format permanently.
+
+* Formatted references
+
+Before version 2.0, LyX used the LaTeX package "prettyref" to produce 
+"formatted references", such as "Section 2.1". This package has several 
+shortcomings when used in a non-English environment, not least of which is 
+that it has no mechanism for internationalization. (See bug #6421 and those
+it references.) 
+
+As of LyX 2.0, users can choose whether to use prettyref or, alternatively,
+the "refstyle" package. The current version of refstyle, v0.5, ships with 
+translations for several languages and provides an easy mechanism for users
+to translate the references it produces into still other languages. It also 
+defines many more commands than prettyref does, including, for example, ones
+to produce "ranges", such as "Sections 2.1 to 2.3". Some LyX developers are 
+already working with the refstyle maintainer, Danie Els, to make it work more 
+easily  with LyX and to extend the translations it provides. (You are invited 
+to contribute translations, too!)
+
+Because many LyX users already have customized prettyref for their purposes,
+LyX 1.6.x files opened in LyX 2.0 will continue to use prettref by default.
+New LyX 2.0 files will use refstyle by default. Both can of course be changed 
+in Document>Settings. Please be advised, however, that prettyref support is to
+be considered deprecated: It may well be removed in LyX 2.1, and all users are
+encouraged to adapt their layout files, etc, to refstyle.
+
+Doing so is fairly simple. With prettyref, one has declarations such as:
+    \newrefformat{for}(Formula \ref{#1}}
+The refstyle equivalent is:
+    \newref{for}{refcmd={Formula \ref{#1}}}
+The translation is obviously trivial.

 
 * Preparing for Unicode:
 
 
 * Preparing for Unicode:
 


@@ -129,8 +176,8 @@ transition as smooth as possible for you. However, there are some caveats:
 
 - User layout files must be converted to UTF-8
 
 
 - User layout files must be converted to UTF-8
 

-  In previous versions, layout styles were allowed to use non-ASCII names
-  using the local encodings. LyX-1.5 now assumes that all layout files are
+  In versions prior to 1.5.0, layout styles were allowed to use non-ASCII names
+  using the local encodings. LyX-1.5 and later assume that all layout files are

   UTF-8 encoded. This means that non-ASCII style names are still allowed
   but they must be valid UTF-8 strings. One way of doing the conversion
   is to use iconv. Using bash, the script below should work:
   UTF-8 encoded. This means that non-ASCII style names are still allowed
   but they must be valid UTF-8 strings. One way of doing the conversion
   is to use iconv. Using bash, the script below should work:


@@ -200,4 +247,4 @@ babel). If you relied, on babel being loaded before your own
 definitions, you can add an extra "\usepackage{babel}" statement at
 the beginning of your preamble.
 
 definitions, you can add an extra "\usepackage{babel}" statement at
 the beginning of your preamble.
 

-http://bugzilla.lyx.org/show_bug.cgi?id=315
+http://www.lyx.org/trac/ticket/315