X-Git-Url: https://git.lyx.org/gitweb/?a=blobdiff_plain;f=UPGRADING;h=4308e8c73b66e19698790a3e68873d3fadc86d58;hb=1eaf66d79ec7c403323f866e33d766a911ef8345;hp=dc5d43224212a15226525345c2d01f88bf0dcb8a;hpb=478bf0cf602e66eb573bfc661a34da3e3b164d96;p=lyx.git
diff --git a/UPGRADING b/UPGRADING
index dc5d432242..4308e8c73b 100644
--- a/UPGRADING
+++ b/UPGRADING
@@ -1,6 +1,99 @@
-How do I upgrade my existing LyX system to version 1.6.x?
+How do I upgrade my existing LyX system to version 2.3.x?
---------------------------------------------------------
+* Upgrading from LyX 2.2.x:
+
+The format of preference and session files has changed. LyX 2.3.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 external_templates file has been split into one file per template,
+which are now located in lib/xtemplates/*.xtemplate. This makes it easier
+to add new templates or modify existing ones. If you have modified
+the external_templates file, you will have to move the modifications to
+the respective *.xtemplate file manually.
+
+If using TeX fonts and en- and em-dashes are output as font ligatures,
+when exporting documents containing en- and em-dashes to the format of
+LyX 2.0 or earlier, the following line has to be manually added to the
+unicodesymbols file of that LyX version:
+0x200b "\\hspace{0pt}" "" "" "" "" # ZERO WIDTH SPACE
+This avoids "uncodable character" issues if the document is actually
+loaded by that LyX version. LyX 2.1 and later versions already have the
+necessary definition in their unicodesymbols file.
+
+If trying to compile documents using R scripts and sweave/knitr, LyX
+2.3.x would not allow for re-running the R scripts, unless the user:
+1) explicitly disables the "Forbid use of needauth converters"
+option in the LyX preferences;
+2) provides explicit consent to the use of the converter on the first
+compilation of the R-enhanced document.
+
+* Upgrading from LyX 2.1.x:
+
+The format of preference and session files has changed. LyX 2.2.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 prefix for subsections in labels and references has been changed from
+"sub:" to "subsec:" in order to avoid a clash with subfloats (conflicting
+\subref command, see bug #7550). Files are automatically converted to the new
+scheme. Please assure that you adapt external refstyle or prettyref definitions
+and your own layout files.
+
+BibTeX errors are now processed and cause LyX to show the errors dialog.
+Before, these errors were ignored, which means that it may happen that
+documents that compiled without error with a previous version now
+compile with error. However, because now in 2.2.x users can click on
+the "Show Output Anyway" button, the document can still be viewed.
+
+Missing characters in the output are now reported as errors. This leads
+to error reports for documents that compiled without error before.
+However, the error was always present but went undetected!
+
+Documents using Times fonts and containing Greek characters may now fail
+to compile under pdflatex for users of MikTeX due to an automatically
+half-installed "grtimes" package. A workaround in LyX was removed as it
+stands in the way of alternative approaches (see bug #6469).
+
+With LuaTeX, LyX now uses polyglossia instead of babel if the language
+package option "Automatic" is selected. In order to use babel, select
+"Always babel" instead. This may be needed if a document uses code that
+is specific to babel.
+
+* 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 typeset of your documents with non-english language can slightly
+change in case of math environments and floats. LyX 2.0.x now has its
+own translation machinery for the strings that are not translated by
+babel.
+
+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.
+
+The UI layout named "classic.ui" and some localized keyboard bindings
+(sv, pt, fi) are not being shipped anymore.
+
* Upgrading from LyX 1.5.x:
The format of preference and session files has changed. LyX 1.6.x is
@@ -82,44 +175,70 @@ have to update them
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
-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
-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
-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:
@@ -129,8 +248,8 @@ transition as smooth as possible for you. However, there are some caveats:
- 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:
@@ -200,4 +319,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.
-http://bugzilla.lyx.org/show_bug.cgi?id=315
+http://www.lyx.org/trac/ticket/315