UPGRADING

   1 How do I upgrade my existing LyX system to version 2.0.x?
   2 ---------------------------------------------------------
   3
   4 * Upgrading from LyX 1.6.x:
   5
   6 The format of preference and session files has changed. LyX 2.0.x is
   7 able to read old files but will save them in the new format.
   8
   9 The format of layout files has changed but, as before, layout2layout.py
  10 will convert older versions to the new format automatically.
  11
  12 The syntax of the languages file has been changed. If you use a
  13 modified languages file, you will need to adapt it to the new syntax.
  14
  15 There has been a large change in how Flex insets are named.
  16 When exporting back to 1.6.x format user-defined flex insets will not
  17 be properly reverted. See RELEASE-NOTES for details.
  18
  19 * Upgrading from LyX 1.5.x:
  20
  21 The format of preference and session files has changed. LyX 1.6.x is
  22 able to read old files but will save them in the new format.
  23
  24 The format of layout files has changed but, as before,
  25 layout2layout.py will convert older versions to the new format
  26 automatically.
  27
  28 * Upgrading from LyX 1.4.x:
  29
  30 The biggest change in 1.5 is the switch to Unicode. Please refer to
  31 the section "Document transfer" below for some things you might take
  32 into account before upgrading.
  33
  34 The format of the preferences file has changed slightly. LyX 1.5.x is
  35 able to read old preferences files, but it will save them in the new
  36 format, so it is not possible to run LyX 1.4.x and 1.5.x with the same
  37 personal configuration directory. If you are upgrading from 1.4.x and
  38 do not intend to continue using 1.4.x, you should delete your existing
  39 preferences file and allow LyX to create a new one.
  40
  41 The list of recently open files is now stored in a different location.
  42 It will therefore be reset when upgrading from LyX 1.4.x.
  43
  44 The format of the layout files has also changed, but LyX 1.5.x uses a
  45 converter layout2layout.py written in python that will convert old layout
  46 files on the fly (see below, section "Document transfer").
  47
  48 * Upgrading from LyX 1.3.x:
  49
  50 The format of the external template file has changed substantially with
  51 LyX 1.4.0. Automatic conversion is not available, so you need to convert
  52 your external templates manually. The new format of the external template
  53 configuration file is described in chapter 6.5 of the Customization Guide.
  54
  55 * Upgrading from LyX 1.2.x:
  56
  57 Since 1.3.0, you have to do the following changes:
  58
  59 One of the perennial bug bears of LyX users in the past has been that
  60 they have had to run Edit->Reconfigure when starting their new version
  61 of the code for the first time. Strange and wonderful things would
  62 often result if they forgot to do this, so LyX 1.3.0 now runs
  63 Edit->Reconfigure automatically the first time the program is run.
  64
  65 If you have your own layout files, you may need to update them a little:
  66
  67 - floats are now defined in the layout file, using the "Float"..."End"
  68   construct. In most cases, adding "Input stdfloats.inc" to your layout
  69   file is enough.
  70
  71 - counters are also defined in the layout files, using the
  72   "Counter"..."End" construct. As for floats, adding "Input
  73   stdfloats.inc" is probably a good idea.
  74
  75 * Upgrading from LyX 1.1.x:
  76
  77 - all layout files should have a "DefaultStyle" entry
  78
  79 - the "Latex" font style does not exist anymore. If you really need
  80   its functionality, consider using the "PassThru" keyword instead.
  81
  82 The new layout format keywords are described in the Customization
  83 manual.
  84
  85 If you have your own binding files (especially math.bind), you will
  86 have to update them
  87
  88 - math-insert now takes a latex macro name as argument, so that
  89   "math-insert sqrt" should now be "\math-insert \sqrt"
  90
  91 - math-greek-toggle is now gone, and should be replaced by explicit
  92   bindings like
  93
  94   \bind "M-m g a"      "math-insert \alpha"
  95
  96
  97 Build requirements
  98 ------------------
  99
 100 LyX 2.0 uses the Qt 4.x toolkit (see INSTALL file).
 101
 102 If you do not have the JPEG library installed, you may need to install it
 103 before you can use the graphics capabilities of LyX. If you do not have the
 104 ImageMagick command-line tools installed, you will need to modify the default
 105 set up of LyX, or install them, in order to get previews of your document's
 106 graphics.
 107
 108 Document transfer
 109 -----------------
 110
 111 * Compatibility with older documents/layouts
 112
 113 LyX 2.0.x uses an external python script, lyx2lyx, to import documents
 114 written using previous versions of LyX. All versions of LyX as far back as
 115 0.10 are supported.
 116
 117 Of course, this means that you must have python (>= 2.3.4, <3)
 118 installed in order to use LyX 2.0.x with your old documents.
 119
 120 lyx2lyx also has the framework in place to be able to convert documents to an
 121 earlier format (which requires python 2.3.4 at least). However, these
 122 converters have only been written for the conversion from 2.0.x to 1.6.x,
 123 1.5.x, 1.4.x and 1.3.x, so versions of LyX older than 1.3.0 will NOT be able to
 124 read documents saved with LyX 2.0.x. The conversion from 2.0.x to 1.6.x-1.3.x
 125 is lossless as long as no new features are used. lyx2lyx tries hard to find
 126 something equivalent for new features such as boxes, but this is known to fail
 127 sometimes. LyX 1.6.9 contains an updated lyx2lyx that can read documents in
 128 2.0.x format.
 129
 130 Furthermore, LyX uses a converter layout2layout.py, also written in python
 131 that will convert old layout files on the fly. You can also call it manually
 132 on your layout files if you want to convert them to 2.0.x format permanently.
 133
 134 * Formatted references
 135
 136 Before version 2.0, LyX used the LaTeX package "prettyref" to produce
 137 "formatted references", such as "Section 2.1". This package has several
 138 shortcomings when used in a non-English environment, not least of which is
 139 that it has no mechanism for internationalization. (See bug #6421 and those
 140 it references.)
 141
 142 As of LyX 2.0, users can choose whether to use prettyref or, alternatively,
 143 the "refstyle" package. The current version of refstyle, v0.5, ships with
 144 translations for several languages and provides an easy mechanism for users
 145 to translate the references it produces into still other languages. It also
 146 defines many more commands than prettyref does, including, for example, ones
 147 to produce "ranges", such as "Sections 2.1 to 2.3". Some LyX developers are
 148 already working with the refstyle maintainer, Danie Els, to make it work more
 149 easily  with LyX and to extend the translations it provides. (You are invited
 150 to contribute translations, too!)
 151
 152 Because many LyX users already have customized prettyref for their purposes,
 153 LyX 1.6.x files opened in LyX 2.0 will continue to use prettref by default.
 154 New LyX 2.0 files will use refstyle by default. Both can of course be changed
 155 in Document>Settings. Please be advised, however, that prettyref support is to
 156 be considered deprecated: It may well be removed in LyX 2.1, and all users are
 157 encouraged to adapt their layout files, etc, to refstyle.
 158
 159 Doing so is fairly simple. With prettyref, one has declarations such as:
 160     \newrefformat{for}(Formula \ref{#1}}
 161 The refstyle equivalent is:
 162     \newref{for}{refcmd={Formula \ref{#1}}}
 163 The translation is obviously trivial.
 164
 165 * Preparing for Unicode:
 166
 167 As of version 1.5.0, LyX uses Unicode internally. This is a major change that
 168 affects documents and layouts likewise. We have tried to do out best to make the
 169 transition as smooth as possible for you. However, there are some caveats:
 170
 171 - User layout files must be converted to UTF-8
 172
 173   In versions prior to 1.5.0, layout styles were allowed to use non-ASCII names
 174   using the local encodings. LyX-1.5 and later assume that all layout files are
 175   UTF-8 encoded. This means that non-ASCII style names are still allowed
 176   but they must be valid UTF-8 strings. One way of doing the conversion
 177   is to use iconv. Using bash, the script below should work:
 178
 179      #! /bin/sh
 180
 181      cd /path/to/layouts
 182      for l in *
 183      do
 184        cp "$l" tmp.txt
 185        iconv -f latin1 -t utf8 tmp.txt -o "$l"
 186      done
 187      rm -f tmp.txt
 188
 189 - Inset encodings and Conversion from earlier LyX versions
 190
 191   As part of the transition to unicode, lyx2lyx (the scripts used for
 192   converting back and forth between different versions of the lyx
 193   files) converts old .lyx files, which may use a number of different
 194   encodings, to UTF-8. This conversion depends on correctly
 195   identifying the language of the text. There were previously some
 196   edge-cases (insets embedded in different-language text type
 197   scenarios) in which the language was incorrectly identified, which
 198   caused some text to appear incorrectly after having upgraded from
 199   older versions. This has now been fixed. Unfortunately, however, the
 200   fix cannot be applied to files which have already been converted
 201   past format 249. So if you have already converted your old files
 202   (using a development version or release candidate), this fix won't
 203   help, unless you still have the originals lying around (and haven't
 204   yet made too many changes to the newer versions ;) ).
 205
 206 Generally, it is probably wise to keep a backup of the old version of your
 207 files, at least until you are sure that the upgrade went smoothly (which it
 208 almost always will).
 209
 210 * Languages/encodings and insets
 211
 212 One of the bugs fixed in LyX 1.5.0 is that previously, there were certain
 213 specific cases in which the LaTeX generated did not correctly reflect
 214 language/encoding transitions in and around insets (footnotes, LyX notes).
 215 After much deliberation, it was decided not to change older files such that
 216 they will still reflect the old LaTeX output; rather, they will now correctly
 217 reflect the situation as it appears in the GUI. This means, however, that if
 218 you mangled the text in the GUI in the older versions, in order that it
 219 generate the correct LaTeX output, the LaTeX will now generate the mangled
 220 text. If this is problematic for you, please get in touch with us on the
 221 developers mailing list, we do have some possible solutions for this.
 222
 223 The effects of this will be more pronounced for RTL (Hebrew, Arabic, Farsi)
 224 users -- though they affect users of other languages as well.
 225
 226 * Floatflt in 1.2.x and older
 227
 228 If you were previously (in LyX 1.1.x) using the floatflt paragraph
 229 option to wrap text around a figure, it was necessary to modify this
 230 for LyX 1.2.0 manually, as described in the manuals. The feature has
 231 been re-implemented as "Floating figure" inset in 1.3.0. Old files will
 232 be converted automatically, but you may want to convert the
 233 1.2.x-style ERT constructs with the native solution (see section 3.8
 234 of the Extended Features manual).
 235
 236 * Babel changes since 1.2.x
 237
 238 Since LyX 1.2.0, the babel package is loaded after the user-defined
 239 preamble (because some packages really need to be loaded before
 240 babel). If you relied, on babel being loaded before your own
 241 definitions, you can add an extra "\usepackage{babel}" statement at
 242 the beginning of your preamble.
 243
 244 http://bugzilla.lyx.org/show_bug.cgi?id=315