When you are working on a new feature you may ask yourself whether it needs
an update of the .lyx file format number.
Whether an update is needed or not is not always obvious.
- Below you can find a list of reasons for file format updates with explanations:
+\end_layout
+
+\begin_layout Description
+Rule
+\begin_inset space ~
+\end_inset
+
+of
+\begin_inset space ~
+\end_inset
+
+thumb:
+\end_layout
+
+\begin_deeper
+\begin_layout Standard
+Whenever there is the danger that a previous version of LyX cannot open
+ a file using the new feature, a file format update is needed.
+\end_layout
+
+\begin_layout Standard
+The file format change allows lyx2lyx rules to implement backwards compatibility.
+\end_layout
+
+\end_deeper
+\begin_layout Standard
+Below you can find a list of reasons for file format updates with explanations:
\end_layout
\begin_layout Description
setting Whenever you introduce a new setting that is stored in the document
header, a file format update is needed.
- This is also true if you add a new valid value to an existing setting,
- e.
+\end_layout
+
+\begin_layout Description
+Removed
+\begin_inset space ~
+\end_inset
+
+document
+\begin_inset space ~
+\end_inset
+
+setting If a certain setting becomes obsolete and gets removed, a file format
+ update is needed.
+\end_layout
+
+\begin_layout Description
+New
+\begin_inset space ~
+\end_inset
+
+valid
+\begin_inset space ~
+\end_inset
+
+value
+\begin_inset space ~
+\end_inset
+
+for
+\begin_inset space ~
+\end_inset
+
+an
+\begin_inset space ~
+\end_inset
+
+existing
+\begin_inset space ~
+\end_inset
+
+setting, e.
\begin_inset space \thinspace{}
\end_inset
g.
-\begin_inset space \space{}
+\end_layout
+
+\begin_deeper
+\begin_layout Description
+\paragraph_spacing single
+Automatically
+\begin_inset space ~
+\end_inset
+
+loaded
+\begin_inset space ~
+\end_inset
+
+math
+\begin_inset space ~
+\end_inset
+
+package The reason for this is that there is no true ERT inset for math
+ formulas: Each command is parsed, and if a user happens to define a local
+ command with the same name as a command that triggers an automatic load
+ of a package, they need to be able to switch off the automatic loading
+ of that package.
+ This switch is stored by the
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+use_package
+\end_layout
+
+\end_inset
+
+ header setting.
+\end_layout
+
+\begin_layout Description
+New
+\begin_inset space ~
\end_inset
-a new language that is stored in
+language that is stored in
\begin_inset Flex Code
status collapsed
\end_inset
.
-\end_layout
+
+\begin_inset Foot
+status open
+
+\begin_layout Plain Layout
+TODO: Discuss if this is really required or whether new languages can be
+ treated similar to new layouts (cf.
+
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "subsec:New-layouts"
-\begin_layout Description
-Removed
-\begin_inset space ~
\end_inset
-document
-\begin_inset space ~
+).
+\end_layout
+
\end_inset
-setting If a certain setting becomes obsolete and gets removed, a file format
- update is needed.
+
\end_layout
+\end_deeper
\begin_layout Description
New
\begin_inset space ~
\end_layout
\begin_layout Description
-New
+Modified
+\begin_inset space ~
+\end_inset
+
+layouts
+\begin_inset space ~
+\end_inset
+
+and
+\begin_inset space ~
+\end_inset
+
+modules with a
+\end_layout
+
+\begin_deeper
+\begin_layout Description
+new
\begin_inset space ~
\end_inset
\end_layout
\begin_layout Description
-Removed
+removed
\begin_inset space ~
\end_inset
style If a style or inset layout is removed in any layout file or module
shipped with \SpecialChar LyX
-, then a new file format is required.
+, a new file format is required.
\end_layout
-\begin_layout Description
-Automatically
-\begin_inset space ~
-\end_inset
+\begin_layout Standard
+However,
+\series bold
+new
+\series default
+ layouts and modules do
+\series bold
+not
+\series default
+ require a file format update.
+\begin_inset Foot
+status collapsed
-loaded
-\begin_inset space ~
-\end_inset
+\begin_layout Plain Layout
+Changed 03/16, see
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "subsec:New-layouts"
-math
-\begin_inset space ~
\end_inset
-package Any new math package that is automatically loaded needs a file format
- update.
- The reason for this is that there is no true ERT inset for math formulas:
- Each command is parsed, and if a user happens to define a local command
- with the same name as a command that triggers an automatic load of a package,
- they need to be able to switch off the automatic loading of that package.
- This switch is stored by the
-\begin_inset Flex Code
-status collapsed
-
-\begin_layout Plain Layout
-use_package
+ for the rationale.
\end_layout
\end_inset
- header setting.
+
\end_layout
+\end_deeper
\begin_layout Standard
If you are still unsure, please ask on the development list.
\end_layout
Remove this note once a consensus is found.
\end_layout
-\begin_layout Plain Layout
-Summary of a recent discussion in lyx-devel by GM.
-\end_layout
-
\begin_layout Plain Layout
See the thread
\begin_inset Quotes eld
In older versions of this document, it was stated that new layout files
require a file format change.
After some discussion it was decided that this is not needed.
- For reference, here are the arguments on each side:
\begin_inset Foot
status open
See
\begin_inset CommandInset href
LatexCommand href
-name "this thread"
+name "the thread “Proposal for a guide on updating layouts”"
target "http://permalink.gmane.org/gmane.editors.lyx.devel/161202"
\end_inset
\end_inset
+
+\end_layout
+\begin_layout Quote
+For reference, here are the arguments on each side
\end_layout
+\begin_deeper
\begin_layout Description
Pro
\begin_inset Quotes eld
\end_layout
\begin_layout Itemize
-All documents produced by 2.2.x can always be edited and exported even if
- x is different.
+All documents produced by 2.2.
+\begin_inset Formula $x$
+\end_inset
+
+ can always be edited and exported even if
+\begin_inset Formula $x$
+\end_inset
+
+ is different.
This is important for people using different machines, or exchanging work
with colleagues.
\end_layout
\end_layout
\begin_layout Itemize
-The lyx2lyx script cannot do anything useful on backward conversion in such
- a case, and the forward conversion would be a no-op.
-\end_layout
-
-\begin_layout Standard
-As said, consensus has been reached that the reasons in favor of not requiring
- a file format change are more compelling.
+The lyx2lyx script cannot do anything useful in such a case.
\end_layout
+\end_deeper
\begin_layout Standard
If you have decided that you are going to add a new layout file to \SpecialChar LyX
itself,
and add it to Git (
\begin_inset Flex Code
-status open
+status collapsed
\begin_layout Plain Layout
git add lib/layouts/newlayout.layout
\end_layout
\begin_layout Standard
-\paragraph_spacing single
where [InsetInfo] is obtained by entering in the minibuffer (Alt+X)
\begin_inset Flex Code
status collapsed
\begin_layout Plain Layout
-\paragraph_spacing single
info-insert textclass <name>
\end_layout
\end_deeper
\begin_layout Enumerate
-Add a template or example file to
+A template or example is strongly encouraged (but not necessarily required).
+ It is also possible to provide both.
+ Add them to
\begin_inset Flex Code
status collapsed
\end_layout
-\begin_layout Standard
-Moreover, because the layout file is completely new, it can be added both
- to the master and the stable branches, in accord with the policy discussed
- in
+\begin_layout Itemize
+The new layout can be added both to the master and the stable branches,
+ in accord with the policy discussed in
\begin_inset CommandInset ref
LatexCommand formatted
reference "subsec:New-layouts"
\end_layout
\begin_layout Standard
-The user can then move an existing document to the new version simply by
- selecting a new document class.
+The user can move an existing document to the new version simply by selecting
+ a new document class.
This step is well supported by \SpecialChar LyX
, with established methods for handling
unsupported styles and other changes.
file as an optional argument in the
\begin_inset Flex Code
-status open
+status collapsed
\begin_layout Plain Layout
\end_layout
\begin_layout Itemize
-Update the GUI name in the old layout file (whose name should not have been
- changed), e.g.:
+Update the GUI name in the old layout file (whose name should not be changed),
+ e.g.:
\begin_inset Newline newline
\end_inset
remove\SpecialChar breakableslash
obsolete\SpecialChar breakableslash
modify settings and styles (similar
- to inclusion of
+ to the inclusion of
\begin_inset Flex Code
-status open
+status collapsed
\begin_layout Plain Layout
*.inc
projects / lyx.git / commitdiff