mirror of
https://git.lyx.org/repos/lyx.git
synced 2024-12-23 13:31:49 +00:00
90adb4f314
Setting this variable to '1' will include also latex messages in ctest log file LastTest.log.
5363 lines
103 KiB
Plaintext
5363 lines
103 KiB
Plaintext
#LyX 2.3 created this file. For more info see http://www.lyx.org/
|
||
\lyxformat 512
|
||
\begin_document
|
||
\begin_header
|
||
\save_transient_properties true
|
||
\origin /systemlyxdir/doc/
|
||
\textclass scrartcl
|
||
\options BCOR8mm,captions=tableheading
|
||
\use_default_options false
|
||
\begin_modules
|
||
logicalmkup
|
||
\end_modules
|
||
\maintain_unincluded_children false
|
||
\language english
|
||
\language_package default
|
||
\inputencoding auto
|
||
\fontencoding global
|
||
\font_roman "lmodern" "default"
|
||
\font_sans "lmss" "default"
|
||
\font_typewriter "lmtt" "default"
|
||
\font_math "auto" "auto"
|
||
\font_default_family default
|
||
\use_non_tex_fonts false
|
||
\font_sc false
|
||
\font_osf false
|
||
\font_sf_scale 100 100
|
||
\font_tt_scale 100 100
|
||
\use_microtype false
|
||
\graphics default
|
||
\default_output_format pdf2
|
||
\output_sync 1
|
||
\bibtex_command default
|
||
\index_command default
|
||
\paperfontsize 12
|
||
\spacing single
|
||
\use_hyperref true
|
||
\pdf_title "LyX's Development manual"
|
||
\pdf_author "LyX Team"
|
||
\pdf_subject "LyX's development documentation"
|
||
\pdf_keywords "LyX, Documentation, Development"
|
||
\pdf_bookmarks true
|
||
\pdf_bookmarksnumbered true
|
||
\pdf_bookmarksopen true
|
||
\pdf_bookmarksopenlevel 1
|
||
\pdf_breaklinks false
|
||
\pdf_pdfborder false
|
||
\pdf_colorlinks true
|
||
\pdf_backref false
|
||
\pdf_pdfusetitle false
|
||
\pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue, pdfpagelayout=OneColumn, pdfnewwindow=true, pdfstartview=XYZ, plainpages=false"
|
||
\papersize a4paper
|
||
\use_geometry false
|
||
\use_package amsmath 1
|
||
\use_package amssymb 1
|
||
\use_package cancel 0
|
||
\use_package esint 0
|
||
\use_package mathdots 1
|
||
\use_package mathtools 0
|
||
\use_package mhchem 1
|
||
\use_package stackrel 0
|
||
\use_package stmaryrd 0
|
||
\use_package undertilde 0
|
||
\cite_engine basic
|
||
\cite_engine_type default
|
||
\biblio_style plain
|
||
\use_bibtopic false
|
||
\use_indices false
|
||
\paperorientation portrait
|
||
\suppress_date false
|
||
\justification true
|
||
\use_refstyle 0
|
||
\notefontcolor #0000ff
|
||
\index Index
|
||
\shortcut idx
|
||
\color #008000
|
||
\end_index
|
||
\secnumdepth 4
|
||
\tocdepth 4
|
||
\paragraph_separation indent
|
||
\paragraph_indentation default
|
||
\quotes_language english
|
||
\papercolumns 1
|
||
\papersides 2
|
||
\paperpagestyle headings
|
||
\tracking_changes false
|
||
\output_changes false
|
||
\html_math_output 0
|
||
\html_css_as_file 0
|
||
\html_be_strict true
|
||
\end_header
|
||
|
||
\begin_body
|
||
|
||
\begin_layout Title
|
||
Developing \SpecialChar LyX
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Subtitle
|
||
Version 2.2.x
|
||
\end_layout
|
||
|
||
\begin_layout Author
|
||
by the \SpecialChar LyX
|
||
Team
|
||
\begin_inset Foot
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
\noindent
|
||
If you have comments or error corrections, please send them to the \SpecialChar LyX
|
||
Documentatio
|
||
n mailing list,
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
\noindent
|
||
<lyx-docs@lists.lyx.org>
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
.
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
\begin_inset CommandInset toc
|
||
LatexCommand tableofcontents
|
||
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Section
|
||
Introduction
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
This manual documents some aspects of \SpecialChar LyX
|
||
development.
|
||
It is currently rather incomplete, but will hopefully be extended in the
|
||
future.
|
||
Meanwhile, additional information can be found in the
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
development
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
subfolder of the \SpecialChar LyX
|
||
source code distribution.
|
||
This document is not translated, since the development language of \SpecialChar LyX
|
||
is
|
||
English.
|
||
If you just want to use \SpecialChar LyX
|
||
, then you don't need to read this manual.
|
||
However, if you want to learn more about how \SpecialChar LyX
|
||
is developed, or even want
|
||
to participate in \SpecialChar LyX
|
||
development, you may find some interesting information
|
||
here.
|
||
\end_layout
|
||
|
||
\begin_layout Section
|
||
File formats
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
\SpecialChar LyX
|
||
uses several custom file formats for configuration files and documents.
|
||
This chapter contains some background concerning these file formats.
|
||
Several file formats are also described in detail in the regular user documenta
|
||
tion.
|
||
\end_layout
|
||
|
||
\begin_layout Subsection
|
||
File Format Numbers
|
||
\end_layout
|
||
|
||
\begin_layout Subsection
|
||
When is an update of the .lyx file format number needed?
|
||
\begin_inset CommandInset label
|
||
LatexCommand label
|
||
name "sec:When-is-an"
|
||
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
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.
|
||
Rule of thumb:
|
||
\end_layout
|
||
|
||
\begin_layout Quote
|
||
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.
|
||
Below you can find a list of reasons for file format updates with explanations:
|
||
\end_layout
|
||
|
||
\begin_layout Description
|
||
New
|
||
\begin_inset space ~
|
||
\end_inset
|
||
|
||
document
|
||
\begin_inset space ~
|
||
\end_inset
|
||
|
||
setting Whenever you introduce a new setting that is stored in the document
|
||
header, a file format update is needed.
|
||
\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.
|
||
\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
|
||
|
||
language that is stored in
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
\backslash
|
||
language
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
.
|
||
|
||
\begin_inset Note Note
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
This requirement is under discussion.
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Description
|
||
New
|
||
\begin_inset space ~
|
||
\end_inset
|
||
|
||
inset Of course a new inset requires a file format update.
|
||
\end_layout
|
||
|
||
\begin_layout Description
|
||
New
|
||
\begin_inset space ~
|
||
\end_inset
|
||
|
||
style If a new style or inset layout is added to any layout file or module
|
||
shipped with \SpecialChar LyX
|
||
, then a new file format is needed in the master (development)
|
||
branch.
|
||
It is possible to backport new styles to the stable version without a file
|
||
format change.
|
||
See
|
||
\begin_inset CommandInset ref
|
||
LatexCommand ref
|
||
reference "subsec:Backporting-new-styles"
|
||
|
||
\end_inset
|
||
|
||
for more information.
|
||
\end_layout
|
||
|
||
\begin_layout Description
|
||
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
|
||
, a new file format is required.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
However,
|
||
\series bold
|
||
new
|
||
\series default
|
||
layouts and modules do
|
||
\series bold
|
||
not
|
||
\series default
|
||
require a file format update (changed 03/16, see
|
||
\begin_inset CommandInset ref
|
||
LatexCommand ref
|
||
reference "subsec:New-layouts"
|
||
|
||
\end_inset
|
||
|
||
).
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
If you are still unsure, please ask on the development list.
|
||
\end_layout
|
||
|
||
\begin_layout Subsection
|
||
\begin_inset CommandInset label
|
||
LatexCommand label
|
||
name "subsec:update_lyx_files"
|
||
|
||
\end_inset
|
||
|
||
How to update the file format number of .lyx files
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Once you come to the conclusion that a file format update is needed, you
|
||
should use the following procedure to perform the update:
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
Implement and test the new feature, including the reading and writing of
|
||
.lyx files.
|
||
Note that any file produced at this stage does not use a valid format,
|
||
so do not use this version of \SpecialChar LyX
|
||
for working on any important documents.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
\begin_inset CommandInset label
|
||
LatexCommand label
|
||
name "enu:Describe_format"
|
||
|
||
\end_inset
|
||
|
||
Describe the new format in
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
development/FORMAT
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
Update the \SpecialChar LyX
|
||
file format number in
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
src/version.h
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
Update the range of file formats in the array
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
format_relation
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
in
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
lib/lyx2lyx/LyX.py
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
\begin_inset CommandInset label
|
||
LatexCommand label
|
||
name "enu:Add-an-entry"
|
||
|
||
\end_inset
|
||
|
||
Add an entry to both format lists (for conversion and reversion) in
|
||
\begin_inset Newline newline
|
||
\end_inset
|
||
|
||
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
lib/lyx2lyx/lyx_2_3.py
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
.
|
||
Add a conversion routine if needed (e.
|
||
\begin_inset space \thinspace{}
|
||
\end_inset
|
||
|
||
g., a new header setting always needs a conversion that adds the new setting,
|
||
but a new document language does not need one).
|
||
Add a reversion routine if needed.
|
||
|
||
\begin_inset Newline newline
|
||
\end_inset
|
||
|
||
While the conversion routine is required to produce a document that is equivalen
|
||
t to the old version, the requirements of the reversion are not that strict.
|
||
If possible, try to produce a proper reversion, using ERT if needed, but
|
||
for some features this might be too complicated.
|
||
In this case, the minimum requirement of the reversion routine is that
|
||
it produces a valid document which can be read by an older \SpecialChar LyX
|
||
.
|
||
If absolutely needed, even data loss is allowed for the reversion.
|
||
(In that case, you might want to add a LyX comment that indicates what
|
||
you have had to do, so the user is at least warned).
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
Since tex2lyx has several implicit file format dependencies caused by sharing
|
||
code with \SpecialChar LyX
|
||
, updating the file format of .lyx files produced by tex2lyx at
|
||
the same time as updating the main .lyx file format is strongly recommended.
|
||
Therefore, a compiler warning will be issued if the \SpecialChar LyX
|
||
and tex2lyx .lyx file
|
||
format numbers differ.
|
||
In many cases the tex2lyx update requires only the first and last item
|
||
of the list below:
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Enumerate
|
||
Update the tex2lyx file format number in
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
src/version.h
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
If the lyx2lyx conversion from the old to the new format is empty, or if
|
||
tex2lyx does not yet output the changed feature, you do not need any further
|
||
tex2lyx changes.
|
||
Otherwise, search for the changed feature in tex2lyx, and adjust the output
|
||
according to the lyx2lyx changes.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
Update the tex2lyx test references as described in
|
||
\begin_inset CommandInset ref
|
||
LatexCommand formatted
|
||
reference "sec:Updating-test-references"
|
||
|
||
\end_inset
|
||
|
||
.
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Enumerate
|
||
If you did not implement full tex2lyx support for the new feature, add a
|
||
line to
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
src/tex2lyx/TODO.txt
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
describing the missing bits.
|
||
Note that it is perfectly fine if you do not add full tex2lyx support for
|
||
a new feature: The updating recommendation above is only issued for the
|
||
syntax of the produced .lyx file.
|
||
It is no problem if some features supported by \SpecialChar LyX
|
||
are still output as ERT
|
||
by tex2lyx.
|
||
The problems in the past that resulted in the update recommendation were
|
||
related to mixed version syntax, not ERT.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
It would be nice if you could create a .lyx test file which contains instances
|
||
of all changed or added features.
|
||
This could then be used to test lyx2lyx and tex2lyx.
|
||
Unfortunately, it has not yet been decided how to collect such examples,
|
||
so please ask on the development list if you want to create one.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
\begin_inset CommandInset label
|
||
LatexCommand label
|
||
name "enu:updatefiles"
|
||
|
||
\end_inset
|
||
|
||
Update LyX's .lyx documentation files to the new format.
|
||
The developer who makes the change knows best what changes to expect when
|
||
inspecting the resulting diff.
|
||
Because of this, you might be able to catch a bug in the lyx2lyx code that
|
||
updates the format just by taking a quick scan through the large diff that
|
||
is the result.
|
||
\begin_inset Note Note
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
Another advantage is that if later we suspect a bug in lyx2lyx we can easily
|
||
see which layout update made an unexpected change by looking at the git
|
||
log of a .lyx file that suffers the problem.
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
To do this, first make sure that there are no changes to the git repository
|
||
that you will not want to commit (this is needed because it will be convenient
|
||
to commit with the command
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
git commit -a
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
).
|
||
Then run the following command in the root folder of the source:
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
python development/tools/updatedocs.py
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
.
|
||
Look at the resulting changes using the command
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
git diff
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
.
|
||
If anything looks surprising, please investigate.
|
||
Keep in mind that the case of
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
LFUNs.lyx
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
is special, because it is first generated with
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
gen_lfuns.py
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
before being converted to the latest format.
|
||
Finally, commit using
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
git commit -a
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
.
|
||
\end_layout
|
||
|
||
\begin_layout Subsection
|
||
Updating the file format number of layout files
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
The procedure for updating the layout files is similar to that in step
|
||
\begin_inset CommandInset ref
|
||
LatexCommand ref
|
||
reference "enu:updatefiles"
|
||
|
||
\end_inset
|
||
|
||
in section
|
||
\begin_inset CommandInset ref
|
||
LatexCommand ref
|
||
reference "subsec:update_lyx_files"
|
||
|
||
\end_inset
|
||
|
||
.
|
||
One need only run
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
python development/tools/updatelayouts.py
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
instead of
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
updatedocs.py
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Note that we do not automatically any local layout used in the
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
.lyx
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
files shipped with \SpecialChar LyX
|
||
because users would then not be able to export to older
|
||
formats.
|
||
For example, if a 2.2.0 user exported a template to 2.1.x format and tried
|
||
to open the file in \SpecialChar LyX
|
||
2.1.x, there would be an error because the file would
|
||
contain a local layout whose format is too new.
|
||
The root reason for this is that we do not support converting layouts to
|
||
older layout formats, as we do for the
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
.lyx
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
file format.
|
||
\end_layout
|
||
|
||
\begin_layout Subsection
|
||
Updating the file format number of bind/ui files
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
A change to the functionality of existing LFUNs can require a conversion
|
||
of
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
.bind
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
and
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
.ui
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
files, and therefore an increment of the LFUN format, as well as a conversion
|
||
of Info insets in
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
.lyx
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
files for manuals.
|
||
The latter cannot be done automatically and also requires an update of
|
||
the \SpecialChar LyX
|
||
file format.
|
||
(Think e.g.
|
||
\begin_inset space \space{}
|
||
\end_inset
|
||
|
||
of someone who might have made a set of \SpecialChar LyX
|
||
teaching manuals for use in their
|
||
own group.)
|
||
\begin_inset Foot
|
||
status open
|
||
|
||
\begin_layout Plain Layout
|
||
\begin_inset Flex URL
|
||
status open
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
http://www.lyx.org/trac/ticket/9794
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
To update the LFUN format:
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
Increment the LFUN file format number in
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
src/LyXAction.h
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
Implement the LFUN conversion in
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
lib/scripts/prefs2prefs_lfuns.py
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
See step
|
||
\begin_inset CommandInset ref
|
||
LatexCommand ref
|
||
reference "enu:updatefiles"
|
||
|
||
\end_inset
|
||
|
||
in section
|
||
\begin_inset CommandInset ref
|
||
LatexCommand ref
|
||
reference "subsec:update_lyx_files"
|
||
|
||
\end_inset
|
||
|
||
but instead of the
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
updatedocs.py
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
command, use this command:
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
bash development/tools/updatelfuns.sh
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
.
|
||
|
||
\begin_inset Note Note
|
||
status open
|
||
|
||
\begin_layout Plain Layout
|
||
This file should really be converted to python.
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
Update Info insets in
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
.lyx
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
files.
|
||
To do so, increment the \SpecialChar LyX
|
||
format and proceed as in
|
||
\begin_inset CommandInset ref
|
||
LatexCommand ref
|
||
reference "subsec:update_lyx_files"
|
||
|
||
\end_inset
|
||
|
||
, steps
|
||
\begin_inset CommandInset ref
|
||
LatexCommand ref
|
||
reference "enu:Describe_format"
|
||
|
||
\end_inset
|
||
|
||
–
|
||
\begin_inset CommandInset ref
|
||
LatexCommand ref
|
||
reference "enu:updatefiles"
|
||
|
||
\end_inset
|
||
|
||
.
|
||
In the lyx2lyx implementation (step
|
||
\begin_inset CommandInset ref
|
||
LatexCommand ref
|
||
reference "enu:Add-an-entry"
|
||
|
||
\end_inset
|
||
|
||
), implement a conversion similar to the one in
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
prefs2prefs_lfuns.py
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
above, as well as a corresponding reversion; for this one can use
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
convert_info_insets
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
from
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
lib/lyx2lyx/lyx2lyx_tools.py
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
.
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Subsection
|
||
Backporting new styles to the stable version
|
||
\begin_inset CommandInset label
|
||
LatexCommand label
|
||
name "subsec:Backporting-new-styles"
|
||
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Starting with the stable \SpecialChar LyX
|
||
2.1 branch, there is a mechanism in place to backport
|
||
new styles to the stable version without the need to update the file format.
|
||
The basic idea is that the new style definition is automatically copied
|
||
to the document preamble so that it can even be used by older minor versions
|
||
that did not yet include the style.
|
||
To backport a new style to the stable version, the following steps are
|
||
needed:
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
Add the line
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
ForceLocal -1
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
to the style definition in the development version.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
Copy the style definition to the stable version, but use
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
ForceLocal 1
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
instead.
|
||
If needed adjust the format to the one used by the stable version (see
|
||
the customization manual for details of the layout file format).
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
For each update of the style in a later stable version, increase the argument
|
||
of
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
ForceLocal
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
by one.
|
||
(In the stable version, the development version should not be touched.)
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
For details about the
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
ForceLocal
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
flag see the customization manual.
|
||
No
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
lyx2lyx
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
support is needed for backported styles: Since the style of the development
|
||
version has an infinite version number, it will always be used.
|
||
Furthermore, since its version number is less than one, the style will
|
||
not be written anymore to the document header for files saved by the new
|
||
version.
|
||
\end_layout
|
||
|
||
\begin_layout Section
|
||
New layouts and modules
|
||
\end_layout
|
||
|
||
\begin_layout Subsection
|
||
\begin_inset CommandInset label
|
||
LatexCommand label
|
||
name "subsec:New-layouts"
|
||
|
||
\end_inset
|
||
|
||
New layouts
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Adding a new layout file to the \SpecialChar LyX
|
||
library makes it an
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
officially supported
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
layout.
|
||
You should therefore think carefully about whether you really want to do
|
||
this and discuss it on lyx-devel, since you will need to be prepared to
|
||
update and fix the layout if necessary.
|
||
If the layout is experimental or for a rarely used document class, then
|
||
it may be better to add it to the relevant portion of the \SpecialChar LyX
|
||
wiki, as a user
|
||
contribution.
|
||
See
|
||
\begin_inset CommandInset href
|
||
LatexCommand href
|
||
target "https://wiki.lyx.org/Layouts/Layouts"
|
||
|
||
\end_inset
|
||
|
||
.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
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.
|
||
\begin_inset Foot
|
||
status open
|
||
|
||
\begin_layout Plain Layout
|
||
See
|
||
\begin_inset CommandInset href
|
||
LatexCommand href
|
||
name "the thread “Proposal for a guide on updating layouts”"
|
||
target "http://permalink.gmane.org/gmane.editors.lyx.devel/161202"
|
||
|
||
\end_inset
|
||
|
||
.
|
||
\end_layout
|
||
|
||
\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_inset
|
||
|
||
New layout files are a file format change
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
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
|
||
|
||
\begin_layout Description
|
||
Con
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
New layout files are not a file format change
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
No new LaTeX classes can be supported in a stable version, and stable versions
|
||
have a typical lifetime of 2–3 years.
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
We have the same situation already with custom layout files: If a document
|
||
using a custom layout file is moved between machines or people, then the
|
||
layout file needs to be exchanged as well.
|
||
If that is not done, then we have a fallback implemented so that such documents
|
||
can still be edited, but not exported, and the user gets a warning.
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
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,
|
||
then, you should do the following:
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
Put your new layout file in
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
lib/layouts/
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
and add it to Git (
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
git add lib/layouts/newlayout.layout
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
) so that it will be committed.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
Add an entry in
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
lib/Makefile.am
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
, so that the new layout actually gets installed.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
Add an entry in
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
lib/doc/LaTeXConfig.lyx
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
containing in particular a line like
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Quote
|
||
Found: [InsetInfo]
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
where [InsetInfo] is obtained by entering in the minibuffer (Alt+X)
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
info-insert textclass <name>
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
.
|
||
This inset will automatically display a boxed
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
yes
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
or
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
no
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
depending on the availability of the package.
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Enumerate
|
||
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
|
||
|
||
\begin_layout Plain Layout
|
||
lib/templates/
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
or
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
lib/examples/
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
, respectively.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
Reconfigure \SpecialChar LyX
|
||
.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
Ensure the autotests for the new layout pass (see
|
||
\begin_inset CommandInset ref
|
||
LatexCommand ref
|
||
reference "par:when-to-run-an-export-test"
|
||
|
||
\end_inset
|
||
|
||
).
|
||
\end_layout
|
||
|
||
\begin_layout Subsection
|
||
New modules
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Adding a new module is very similar to adding a new layout.
|
||
Therefore, the previous section applies to new modules as well, with two
|
||
exceptions:
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
You only need to add an entry to
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
lib/doc/LaTeXConfig.lyx
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
if the module requires a LaTeX package.
|
||
In that case, the command for entering the InsetInfo is:
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
\paragraph_spacing single
|
||
info-insert package <name>
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
Modules do not need a template, only an example, which is strongly encouraged
|
||
but not necessarily required.
|
||
\end_layout
|
||
|
||
\begin_layout Subsection
|
||
Layouts for document classes with incompatible versions
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
\begin_inset Note Greyedout
|
||
status open
|
||
|
||
\begin_layout Description
|
||
Note: This section is currently only a proposal under discussion.
|
||
Please correct/amend as suited.
|
||
Remove this note once a consensus is found.
|
||
\end_layout
|
||
|
||
\begin_layout Plain Layout
|
||
See the thread
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
Proposal for a guide on updating layouts
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
for details and background
|
||
\end_layout
|
||
|
||
\begin_layout Plain Layout
|
||
http://permalink.gmane.org/gmane.editors.lyx.devel/161126
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Every now and then, there are changes to LaTeX document classes that break
|
||
backwards compatibility.
|
||
\begin_inset Foot
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
Uwe has suggested we implement automatic detection of changes in class files.
|
||
This could be done by running a script every month that checks if a document
|
||
class was changed at CTAN and at the homepages of the scientific journals.
|
||
If it reports a change, we can check if our template and layout file are
|
||
still usable with the changed document class.
|
||
(This is different from the autotests insofar, as this would also catch
|
||
changes that do not result in compilation errors.)
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
Reasons can be a new name for the
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
*.cls
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
file, removed \SpecialChar LaTeX
|
||
commands, or both.
|
||
How should this best be handled in \SpecialChar LyX
|
||
?
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
The idea is to support the new version with a new \SpecialChar LyX
|
||
layout so that:
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
Existing documents can still be opened in \SpecialChar LyX
|
||
and will continue to work on
|
||
systems where the old version is still installed.
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
With differently named
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
*.cls
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
files, \SpecialChar LyX
|
||
can check for the availability of the particular version and reflect
|
||
this in the GUI.
|
||
Different document class versions with the same file name are currently
|
||
(2.2.x) not detected by the configuration script.
|
||
This is planned for 2.3.
|
||
\begin_inset Foot
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
https://www.mail-archive.com/lyx-devel@lists.lyx.org/msg192467.html
|
||
\end_layout
|
||
|
||
\begin_layout Plain Layout
|
||
However, what we really need is version detection for the configuration,
|
||
so that the user can be warned if the required class file has the wrong
|
||
version.
|
||
(If the class file keeps the name over the version change, only one of
|
||
the two layout files generates compilable documents.)
|
||
\end_layout
|
||
|
||
\begin_layout Plain Layout
|
||
This point was also made here: http://permalink.gmane.org/gmane.editors.lyx.devel/143
|
||
798
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\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_inset
|
||
|
||
.
|
||
No lyx2lyx conversion is then required when a new major version is released.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
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.
|
||
This way, no lyx2lyx code is required.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
The steps to support a new version of an existing document class are thus:
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
Create a new layout file including the upstream version in the name (avoid
|
||
special characters like spaces and dots), e.g.
|
||
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
acmsiggraph-v0-92.layout
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
.
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
Include the name of the
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
*.cls
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
file as an optional argument in the
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
\backslash
|
||
DeclareLaTeXClass
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
line and include the version number in the GUI name:
|
||
\begin_inset Newline newline
|
||
\end_inset
|
||
|
||
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
\backslash
|
||
DeclareLaTeXClass[acmsiggraph]{ACM SIGGGRAPH (v.
|
||
\begin_inset space ~
|
||
\end_inset
|
||
|
||
0.92)}
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
Update the GUI name in the old layout file (whose name should not be changed),
|
||
e.g.:
|
||
\begin_inset Newline newline
|
||
\end_inset
|
||
|
||
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
\backslash
|
||
DeclareLaTeXClass{ACM SIGGRAPH (<= v.
|
||
\begin_inset space ~
|
||
\end_inset
|
||
|
||
0.91, obsolete)}
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
To avoid duplicate definitions, the new layout can
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
Input
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
the old layout file and add\SpecialChar breakableslash
|
||
remove\SpecialChar breakableslash
|
||
obsolete\SpecialChar breakableslash
|
||
modify settings and styles (similar
|
||
to the inclusion of
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
*.inc
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
files).
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Standard
|
||
It may be tempting to let the new layout be the
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
master version
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
and have the old layout import it.
|
||
However, this should not be done because any changes to the new layout
|
||
would need undo steps in the importing old layout.
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Itemize
|
||
If the new LaTeX document class obsoletes the old one, update the example
|
||
and template files to use the new layout.
|
||
Add a note about the changes (preferably with a pointer to the documentation
|
||
of the changes).
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Standard
|
||
This way, new documents based on the template or example will use the up-to-date
|
||
document class version.
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Standard
|
||
\begin_inset Newpage newpage
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Section
|
||
Tests
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Automated tests are an important tool to detect bugs and regressions in
|
||
software development.
|
||
Some projects like gcc even require each bug fix to be accompanied by a
|
||
test case for the automatic test suite, that would detect this bug.
|
||
Testing interactive features automatically is of course very hard, but
|
||
core functionality like document import and export can be tested quite
|
||
easily, and some tests of this kind exist.
|
||
\end_layout
|
||
|
||
\begin_layout Subsection
|
||
unit tests
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
There are attempts to set up a suite of unit tests for LyX.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
TODO: describe what is done and what is still to do.
|
||
\end_layout
|
||
|
||
\begin_layout Subsection
|
||
tex2lyx tests
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
The tex2lyx tests are located in the
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
src/tex2lyx/test
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
subfolder of the \SpecialChar LyX
|
||
source code distribution.
|
||
The actual testing is performed by the simple python script
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
src/tex2lyx/test/runtests.py
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
.
|
||
Each test consists of two files:
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
<test name>.tex
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
contains the \SpecialChar LaTeX
|
||
code that should be tested.
|
||
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
<test name>.lyx.lyx
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
contains the expected output of tex2lyx.
|
||
When a test is run, the actual produced output is compared with the stored
|
||
reference output.
|
||
The test passes if both are identical.
|
||
The test machinery is also able to generate a file
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
<test name>.lyx.tex
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
by exporting the produced .lyx file with \SpecialChar LyX
|
||
again.
|
||
This may be useful for roundtrip comparisons.
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
Running the tests
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
The tex2lyx tests can be run in several ways.
|
||
When in the
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
src/tex2lyx
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
subfolder of the build directory, the commands
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
ctest
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
(cmake, all platforms),
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
make test
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
(cmake, when using a make based build system and not MSVC) or
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
make alltests
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
(autotools) will run the tex2lyx tests.
|
||
Alternatively, in the root of the build directory, the command
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
ctest -R tex2lyx
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
runs all tests whose names match the regex
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
tex2lyx
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
.
|
||
Another way to run the tex2lyx tests in the root build directory is to
|
||
instead use the command
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
ctest -L '(cmplyx|roundtrip)'
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
, which runs all tests categorized with the label
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
roundtrip
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
or
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
cmplyx
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
.
|
||
If a test fails, the differences between the expected and actual results
|
||
are output in unified diff format.
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
Updating test references
|
||
\begin_inset CommandInset label
|
||
LatexCommand label
|
||
name "sec:Updating-test-references"
|
||
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
In some cases a changed tex2lyx output is not a test failure, but wanted,
|
||
e.
|
||
\begin_inset space \thinspace{}
|
||
\end_inset
|
||
|
||
g.
|
||
\begin_inset space \space{}
|
||
\end_inset
|
||
|
||
if a tex2lyx bug was fixed, or a new feature was added.
|
||
In these cases the stored references need to be updated.
|
||
To do so if using autotools, call
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
make updatetests
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
in the
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
src/tex2lyx
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
subdirectory of the build directory.
|
||
If instead using CMake, call
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
make updatetex2lyxtests
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
in the build directory or in the
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
src/tex2lyx/test
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
subdirectory of the build directory.
|
||
\begin_inset Foot
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
Note that this is a case where a make target in the build directory can
|
||
affect the source directory, which might not be advisable.
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
On Windows do the following:
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
Assure that the path to the python.exe is in your system PATH variable.
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
Double-click on the file
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
updatetex2lyxtests.vcxproj
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
in the build directory or in the
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
src/tex2lyx/test
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
subdirectory of your build directory.
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
In the appearing MSVC program right-click on the project
|
||
\family sans
|
||
updatetex2lyxtests
|
||
\family default
|
||
in the project explorer and chose
|
||
\family sans
|
||
Create
|
||
\family default
|
||
.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
For convenience, these commands also produce re-exported roundtrip .lyx.tex
|
||
files.
|
||
Please examine the changed output carefully before committing the changed
|
||
files to the repository: Since the test machinery does not do a roundtrip
|
||
test .tex
|
||
\begin_inset Formula $\Rightarrow$
|
||
\end_inset
|
||
|
||
.lyx
|
||
\begin_inset Formula $\Rightarrow$
|
||
\end_inset
|
||
|
||
.tex, and does not compare the produced dvi or pdf output, it assumes that
|
||
the stored .lyx reference produces correct output if processed by \SpecialChar LyX
|
||
.
|
||
There is only one chance to detect wrong output: before committing a new
|
||
reference.
|
||
Once it is committed, it is quite difficult to verify whether it is correct.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Please
|
||
\emph on
|
||
do not
|
||
\emph default
|
||
update the test references by opening them with \SpecialChar LyX
|
||
or directly running lyx2lyx
|
||
on them.
|
||
This would not work, since lyx2lyx and \SpecialChar LyX
|
||
produce slightly different files
|
||
regarding insignificant whitespace and line breaks.
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
Adding a new test
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
In many cases tests for new features may be added to one of the existing
|
||
test files, but sometimes this is not possible or not wanted.
|
||
Then a new test file needs to be added:
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
Create the new file
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
src/tex2lyx/test/<test name>.tex
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
and run tex2lyx in roundtrip mode to produce the file
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
src/tex2lyx/test/<test name>.lyx.lyx
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
.
|
||
This file will be the new reference.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
Once you confirmed that the tex2lyx output is correct, add the new files
|
||
to the corresponding lists in
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
src/tex2lyx/test/runtests.py
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
,
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
src/tex2lyx/Makefile.am
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
and
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
src/tex2lyx/test/CMakeLists.txt
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
Commit the changes to the repository, or send a patch to the development
|
||
list and ask for committing if you do not have commit rights.
|
||
\end_layout
|
||
|
||
\begin_layout Subsection
|
||
ctest automatic tests
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Some tests are located in the
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
development/autotests/
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
subfolder of the \SpecialChar LyX
|
||
source code distribution.
|
||
|
||
\begin_inset Foot
|
||
status open
|
||
|
||
\begin_layout Plain Layout
|
||
The README document in this folder only describes the
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
keytests
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
subset of autotests!
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
These tests can be run by the commands
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
ctest
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
in the
|
||
\emph on
|
||
build directory
|
||
\emph default
|
||
(all platforms) or (when using a make based build system and not MSVC)
|
||
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
make test
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
in the
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
autotests/
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
subfolder of the
|
||
\emph on
|
||
build directory
|
||
\emph default
|
||
.
|
||
The test logs are written to the
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
Testing/Temporary/
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
subfolder of the
|
||
\emph on
|
||
|
||
\emph default
|
||
build directory.
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
Export tests
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
The export tests are integration tests.
|
||
They take longer to run and are more likely to break than the tex2lyx tests.
|
||
Nevertheless, they have caught many regressions and without a better alternativ
|
||
e it is important to keep them up-to-date and understand how they work.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
The export tests
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
reuse
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
documentation, template, and example documents.
|
||
In addition, there are a number of dedicated sample documents in the
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
autotests/export/
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
subfolder of the \SpecialChar LyX
|
||
source code distribution.
|
||
All samples are (after copying and eventual processing by scripts) exported
|
||
to various output formats via the
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
—export-to
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
command line option.
|
||
The tests checks for errors reported by LyX.
|
||
(However, error-free export is no guarantee for an error-free output document.)
|
||
\end_layout
|
||
|
||
\begin_layout Paragraph
|
||
\begin_inset CommandInset label
|
||
LatexCommand label
|
||
name "par:when-to-run-an-export-test"
|
||
|
||
\end_inset
|
||
|
||
Expectations of LyX developers
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Because the export tests are integration tests and take a long time to run,
|
||
LyX developers are rarely expected to run all of the tests.
|
||
Here are some good practices to follow by developers:
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
When making a non-trivial change to a .layout file, run the export and layout
|
||
tests corresponding with that .layout file.
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
When making non-trivial changes to a .lyx file, run the export tests correspondin
|
||
g to that .lyx file.
|
||
|
||
\begin_inset Foot
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
This rule is due to revision.
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Plain Layout
|
||
There is an objection from the documentation maintainer that working on
|
||
the documentation must not be complicated by having to consider non-standard
|
||
exports.
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
successful compiling/testing an edited documentation file with pdflatex
|
||
suffices to ensure it can be commited, not tests with other exports are
|
||
required.
|
||
\end_layout
|
||
|
||
\begin_layout Plain Layout
|
||
If sudden failures with other exports due to “half-tested” documentation
|
||
updates are a problem for the test maintainer, the test suite should use
|
||
copies that are
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
copied to a cache dir (autotests/samples/doc/, say) but not changed,
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
updated regularely (but on a time chosen by the test suite maintainer) from
|
||
the originals in lib/doc/
|
||
\end_layout
|
||
|
||
\begin_layout Plain Layout
|
||
This way,
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
no test will fail due to ongoing work on documentation,
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
the documentation is still tested in full (with some delay),
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
failures with non-default export can be examined and handled accordingly
|
||
in one run with the cache update,
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
“interesting failures” (like the nested-language+polyglossia problem in
|
||
es/Customization can be separated and moved into dedicated test samples.
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
When making non-trivial changes to LyX's \SpecialChar LaTeX
|
||
export code (e.g.
|
||
touching the encoding code or package handling code that you expect will
|
||
change the exported \SpecialChar LaTeX
|
||
in some way):
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Standard
|
||
\paragraph_spacing single
|
||
Consider running all of the export tests before and after your change.
|
||
If there are differences, please reconcile these (i.e.
|
||
fix the bug or fix the tests)
|
||
\emph on
|
||
before
|
||
\emph default
|
||
committing.
|
||
Ask for help if you're not sure what to.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
If you do not want to run the tests,
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
post the patch on the list and others will run the tests and eventually
|
||
ask for fixes, or
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
commit, but be prepared to fix eventually arising problems or to revert
|
||
the commit if there is no easy fix.
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Itemize
|
||
Understand how to interpret test failures.
|
||
If your commit is found to have broken a test, you should be able to interpret
|
||
the test results when made aware of them.
|
||
See Section
|
||
\begin_inset CommandInset ref
|
||
LatexCommand ref
|
||
reference "subsec:Interpreting-export-tests"
|
||
|
||
\end_inset
|
||
|
||
.
|
||
\end_layout
|
||
|
||
\begin_layout Paragraph
|
||
\begin_inset CommandInset label
|
||
LatexCommand label
|
||
name "par:export-test-output-formats"
|
||
|
||
\end_inset
|
||
|
||
Output formats
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
The following output formats are currently tested for each sample document
|
||
(see
|
||
\begin_inset CommandInset ref
|
||
LatexCommand ref
|
||
reference "par:Export-test-filtering"
|
||
|
||
\end_inset
|
||
|
||
for exceptions):
|
||
\end_layout
|
||
|
||
\begin_layout Labeling
|
||
\labelwidthstring 00.00.0000
|
||
LyX:
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Labeling
|
||
\labelwidthstring 00.00.0000
|
||
lyx16 LyX 1.6 file format (lyx2lyx)
|
||
\end_layout
|
||
|
||
\begin_layout Labeling
|
||
\labelwidthstring 00.00.0000
|
||
lyx21 LyX 2.1 file format (lyx2lyx)
|
||
\end_layout
|
||
|
||
\begin_layout Labeling
|
||
\labelwidthstring 00.00.0000
|
||
xhtml LyXHTML (native LyX HTML export)
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Labeling
|
||
\labelwidthstring 00.00.0000
|
||
LyX
|
||
\begin_inset space ~
|
||
\end_inset
|
||
|
||
+
|
||
\begin_inset space ~
|
||
\end_inset
|
||
|
||
LaTeX:
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Labeling
|
||
\labelwidthstring pdf5msystemFM
|
||
dvi DVI (8-bit latex)
|
||
\end_layout
|
||
|
||
\begin_layout Labeling
|
||
\labelwidthstring pdf5msystemFM
|
||
dvi3_texF DVI (LuaTeX with 8-bit TeX fonts)
|
||
\end_layout
|
||
|
||
\begin_layout Labeling
|
||
\labelwidthstring pdf5msystemFM
|
||
dvi3_systemF DVI (LuaTeX with Unicode fonts)
|
||
\end_layout
|
||
|
||
\begin_layout Labeling
|
||
\labelwidthstring pdf5msystemFM
|
||
pdf2 PDF (pdflatex)
|
||
\end_layout
|
||
|
||
\begin_layout Labeling
|
||
\labelwidthstring pdf5msystemFM
|
||
pdf4_texF PDF (XeTeX with 8-bit TeX fonts)
|
||
\end_layout
|
||
|
||
\begin_layout Labeling
|
||
\labelwidthstring pdf5msystemFM
|
||
pdf4_systemF PDF (XeTeX with Unicode fonts)
|
||
\end_layout
|
||
|
||
\begin_layout Labeling
|
||
\labelwidthstring pdf5msystemFM
|
||
pdf5_texF PDF (LuaTeX with 8-bit TeX fonts)
|
||
\end_layout
|
||
|
||
\begin_layout Labeling
|
||
\labelwidthstring pdf5msystemFM
|
||
pdf5_systemF PDF (LuaTeX with Unicode fonts)
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Labeling
|
||
\labelwidthstring 00.00.0000
|
||
LyX
|
||
\begin_inset space ~
|
||
\end_inset
|
||
|
||
+
|
||
\begin_inset space ~
|
||
\end_inset
|
||
|
||
LaTeX
|
||
\begin_inset space ~
|
||
\end_inset
|
||
|
||
+
|
||
\begin_inset space ~
|
||
\end_inset
|
||
|
||
postprocessing:
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Labeling
|
||
\labelwidthstring pdf5msystemFM
|
||
pdf DVI -> PS (dvips) -> PDF (ps2pdf)
|
||
\end_layout
|
||
|
||
\begin_layout Labeling
|
||
\labelwidthstring pdf5msystemFM
|
||
pdf3 DVI -> PDF (dvipdfm)
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Labeling
|
||
\labelwidthstring 00.00.0000
|
||
not
|
||
\begin_inset space ~
|
||
\end_inset
|
||
|
||
tested: (or only if set as default output format in the document source)
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Labeling
|
||
\labelwidthstring pdf5msystemFM
|
||
latex LaTeX (plain)
|
||
\end_layout
|
||
|
||
\begin_layout Labeling
|
||
\labelwidthstring pdf5msystemFM
|
||
luatex LaTeX (LuaTeX)
|
||
\end_layout
|
||
|
||
\begin_layout Labeling
|
||
\labelwidthstring pdf5msystemFM
|
||
dviluatex LaTeX (dviluatex)
|
||
\end_layout
|
||
|
||
\begin_layout Labeling
|
||
\labelwidthstring pdf5msystemFM
|
||
pdflatex LaTeX (pdflatex)
|
||
\end_layout
|
||
|
||
\begin_layout Labeling
|
||
\labelwidthstring pdf5msystemFM
|
||
platex LaTeX (pLaTeX)
|
||
\end_layout
|
||
|
||
\begin_layout Labeling
|
||
\labelwidthstring pdf5msystemFM
|
||
xetex LaTeX (XeTeX)
|
||
\end_layout
|
||
|
||
\begin_layout Labeling
|
||
\labelwidthstring pdf5msystemFM
|
||
eps3 EPS (encapsulated Postscript) (cropped)
|
||
\end_layout
|
||
|
||
\begin_layout Labeling
|
||
\labelwidthstring pdf5msystemFM
|
||
ps DVI -> Postscript (dvips)
|
||
\end_layout
|
||
|
||
\begin_layout Labeling
|
||
\labelwidthstring pdf5msystemFM
|
||
odf
|
||
\end_layout
|
||
|
||
\begin_layout Labeling
|
||
\labelwidthstring pdf5msystemFM
|
||
text (nor text2, ..., text4)
|
||
\end_layout
|
||
|
||
\begin_layout Labeling
|
||
\labelwidthstring pdf5msystemFM
|
||
textparagraph
|
||
\end_layout
|
||
|
||
\begin_layout Labeling
|
||
\labelwidthstring pdf5msystemFM
|
||
word
|
||
\end_layout
|
||
|
||
\begin_layout Labeling
|
||
\labelwidthstring pdf5msystemFM
|
||
word2
|
||
\end_layout
|
||
|
||
\begin_layout Labeling
|
||
\labelwidthstring pdf5msystemFM
|
||
wordhtml
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Paragraph
|
||
\begin_inset CommandInset label
|
||
LatexCommand label
|
||
name "par:Configuring-ctests"
|
||
|
||
\end_inset
|
||
|
||
Configuring the tests
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
To enable the export autotests, add the
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
-DLYX_ENABLE_EXPORT_TESTS=ON
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
flag.
|
||
For example:
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
cmake -DLYX_ENABLE_EXPORT_TESTS=ON /path/to/source
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
\noindent
|
||
This flag will increase the time for the cmake command by several seconds,
|
||
mainly because of the process of inverting tests (see Section
|
||
\begin_inset CommandInset ref
|
||
LatexCommand ref
|
||
reference "subsec:Interpreting-export-tests"
|
||
|
||
\end_inset
|
||
|
||
).
|
||
\end_layout
|
||
|
||
\begin_layout Paragraph
|
||
\begin_inset CommandInset label
|
||
LatexCommand label
|
||
name "par:ctest-options"
|
||
|
||
\end_inset
|
||
|
||
Running the tests
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
To run all tests, in the build directory simply run the command
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
ctest
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
.
|
||
A full, up-to-date TeXLive installation is recommended to run the tests.
|
||
Otherwise, some tests will fail.
|
||
Tests with additional requirements are labeled
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
unreliable:nonstandard
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
.
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
To run only some of the tests, use command line options (see examples below):
|
||
\end_layout
|
||
|
||
\begin_layout Labeling
|
||
\labelwidthstring -R
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
-R <pattern>
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
Run only the tests whose names match the given regular expression.
|
||
\end_layout
|
||
|
||
\begin_layout Labeling
|
||
\labelwidthstring -R
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
-L <pattern>
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
Run only the tests whose labels match the given regular expression.
|
||
A test may have more that one label.
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Labeling
|
||
\labelwidthstring -R
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
-E <pattern>
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
Exclude the tests whose names match the given regular expression.
|
||
\end_layout
|
||
|
||
\begin_layout Labeling
|
||
\labelwidthstring -R
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
-LE <pattern>
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
Exclude the tests whose labels match the given regular expression.
|
||
Cannot be combined with
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
-L
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
The following options help to find good selection patterns:
|
||
\end_layout
|
||
|
||
\begin_layout Labeling
|
||
\labelwidthstring -R
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
-N
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
List the tests that would be run but not actually run them.
|
||
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Standard
|
||
Useful in conjunction with the -R, -L, -E and -LE options, e.g., if you want
|
||
to know how many tests there are or whether your
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
<pattern>
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
regular expression did what you expected.
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Labeling
|
||
\labelwidthstring -R
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
\SpecialChar nobreakdash
|
||
\SpecialChar nobreakdash
|
||
print-labels
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
print the list of all labels associated with the test set.
|
||
Can also be combined with -R, -L, -E, ...
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Other useful options are:
|
||
\end_layout
|
||
|
||
\begin_layout Labeling
|
||
\labelwidthstring -R
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
-j <jobs>
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
Run the tests in parallel using the given number of jobs.
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Standard
|
||
We are still working on getting the tests to run in parallel.
|
||
However, when running the tests in parallel, sometimes tests fail that
|
||
pass when run sequentially.
|
||
A reasonable approach is to first run the tests in parallel and then run
|
||
the failed tests sequentially.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
For example, to run 8 jobs at a time:
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
ctest -j8
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
ctest \SpecialChar nobreakdash
|
||
\SpecialChar nobreakdash
|
||
rerun-failed
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
When specifying a subset of the tests (e.g.
|
||
using
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
\SpecialChar nobreakdash
|
||
R <pattern>
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
), the same subset must be specified when using the
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
\SpecialChar nobreakdash
|
||
\SpecialChar nobreakdash
|
||
rerun-failed
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
option because it is the test numbers that are used to index which tests
|
||
failed on the previous run.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
\noindent
|
||
Note that some tests cannot be run in parallel.
|
||
These tests are marked in the code with the
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
\noindent
|
||
RUN_SERIAL ON
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
CMake property.
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Labeling
|
||
\labelwidthstring -R
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
\SpecialChar nobreakdash
|
||
\SpecialChar nobreakdash
|
||
timeout <seconds>
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
Set a global timeout on all tests that do not already have a timeout set
|
||
on them.
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Standard
|
||
There have been bugs in LyX and in \SpecialChar LaTeX
|
||
which cause compilation to hang, and
|
||
without a timeout a test might never stop (in one case there was even a
|
||
memory leak).
|
||
If a test times out, the
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
ctest
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
command exits with error, but you can distinguish between a timed out test
|
||
and a failed test in the output reported at the end of the
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
ctest
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
command.
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Standard
|
||
See the manual (
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
man ctest
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
) the full list of command line options.
|
||
\end_layout
|
||
|
||
\begin_layout Paragraph
|
||
Examples
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
run only the export tests:
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
ctest -L export
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
run inverted tests:
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
ctest -L "inverted|suspended"
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
list all export tests which match any of the labelling patterns:
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
ctest -N -R "
|
||
\backslash
|
||
..*_export/"
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
exclude rarely used output formats and post-processing tests
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
ctest -L export -E "_(texF|dvi3|pdf3?)"
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Paragraph
|
||
\begin_inset CommandInset label
|
||
LatexCommand label
|
||
name "subsec:Interpreting-export-tests"
|
||
|
||
\end_inset
|
||
|
||
Interpreting the export test results
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
A test can fail for several reasons, not all of them bad.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
A new or edited sample document may be incompatible with some output formats.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
A dependency is not met (e.g.
|
||
the \SpecialChar LaTeX
|
||
class file).
|
||
One hint that this is the case is that the corresponding
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
check_load
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
test will likely also fail.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
An inverted test fails to fail (i.e.
|
||
export that previously failed now works).
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
An external dependency was updated (e.g.
|
||
\SpecialChar TeX
|
||
Live).
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
A recent code change introduced a bug.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
\begin_inset CommandInset label
|
||
LatexCommand label
|
||
name "enu:exposed"
|
||
|
||
\end_inset
|
||
|
||
A change in a document exposed a previously unknown bug or an incompatibility
|
||
with an export format (e.g.
|
||
Lua\SpecialChar LaTeX
|
||
).
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Because the .lyx files are exported in several formats, it is not surprising
|
||
that many of the exports fail.
|
||
This expectation of failure is addressed by
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
inverting
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
the tests, that is, by marking the test as
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
passing
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
if the export exits with error and as
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
failing
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
if the export succeeds
|
||
\emph on
|
||
.
|
||
|
||
\emph default
|
||
It follows that these expected failures will not show up as failed tests
|
||
in the test results and thus will not pollute the
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
good
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
tests.
|
||
If the export actually succeeds, then the test will fail.
|
||
The purpose of this failure is to get your attention—something has changed,
|
||
possibly for the better.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
We try to document why a test is inverted or ignored.
|
||
See the comment (prefixed with
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
#
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
) above the block in which the test is listed as inverted or ignored in
|
||
the files
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
development/autotests/invertedTests
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
,
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
development/autotests/unreliableTests
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
and
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
development/autotests/ignoredTests
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
.
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
A good question is why do we enable the tests for non-default formats? The
|
||
answer is that if a non-default route is broken it is often because a bug
|
||
was introduced in LyX and not because a document-specific change was made
|
||
that is not supported by the route.
|
||
In other words, there is a high signal/noise ratio in the export tests
|
||
for some non-default formats.
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
When a test or several tests fail, consider checking the files in the
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
Testing/Temporary/
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
subdirectory of your build directory.
|
||
In this subdirectory are three files: the file
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
LastTestsFailed.log
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
simply lists the tests that failed on your last
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
ctest
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
command; the
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
LastTest.log
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
file contains the output from the tests (and often has details explaining
|
||
why a test failed); and the
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
CTestCostData.txt
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
file lists the times that it took to run the tests.
|
||
\end_layout
|
||
|
||
\begin_layout Paragraph
|
||
What action should you take if a test fails?
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
\paragraph_spacing single
|
||
It is always good to check manually why something fails and if it passes
|
||
if the PDF output is good.
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
Generally, if a change breaks compilation for the target format (for the
|
||
manuals pdf2) without solving some important other issue,
|
||
\emph on
|
||
fix or revert the commit
|
||
\emph default
|
||
that led to failure.
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
If it is not possible to (immediately) fix the failure but there are reasons
|
||
not to revert the commit (e.g.
|
||
it fixes another more important issue),
|
||
\emph on
|
||
invert
|
||
\emph default
|
||
the failing test case (see
|
||
\begin_inset CommandInset ref
|
||
LatexCommand ref
|
||
reference "par:Inverted-tests"
|
||
|
||
\end_inset
|
||
|
||
).
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
If an
|
||
\emph on
|
||
inverted
|
||
\emph default
|
||
test case fails because the export now works,
|
||
\emph on
|
||
uninvert
|
||
\emph default
|
||
the test by removing the pattern from the
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
invertedTests
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
file) (see
|
||
\begin_inset CommandInset ref
|
||
LatexCommand ref
|
||
reference "par:Inverted-tests"
|
||
|
||
\end_inset
|
||
|
||
).
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
If the export did not fail previously but led to wrong output (PDF, say),
|
||
\begin_inset Foot
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
Non-failing test with wrong output should be labeledas
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
unreliable:wrong_output
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
(
|
||
\begin_inset CommandInset ref
|
||
LatexCommand ref
|
||
reference "par:Unreliable-tests"
|
||
|
||
\end_inset
|
||
|
||
).
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
it is in fact an improvement when the test now fails.
|
||
|
||
\emph on
|
||
Invert
|
||
\emph default
|
||
the failing test case (see
|
||
\begin_inset CommandInset ref
|
||
LatexCommand ref
|
||
reference "par:Inverted-tests"
|
||
|
||
\end_inset
|
||
|
||
).
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
In case of tests failing due to missing requirements (tests labeled
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
unreliable:nonstandard
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
or testing on a system with only a subset of TeXLive installed), ignore
|
||
the failure, ask for someone else to run the test, or install the missing
|
||
resources and try again.
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
Check the log file Testing/Temporary/LastTest.log.
|
||
In case of latex-errors rerun the failing test with environment variable
|
||
'LAX_DEBUG_LATEX' set to '1'.
|
||
This will include latex messages in LastTest.log, so it should be easier
|
||
to interpret the fail-reason.
|
||
\end_layout
|
||
|
||
\begin_layout Paragraph
|
||
\begin_inset CommandInset label
|
||
LatexCommand label
|
||
name "par:Inverted-tests"
|
||
|
||
\end_inset
|
||
|
||
Inverted tests
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Test cases whose name matches a pattern in the file
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
development/autotests/invertedTests
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
get the label
|
||
\emph on
|
||
inverted
|
||
\emph default
|
||
.
|
||
They get also the test property
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
WILL_FAIL
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
, i.e.
|
||
they are reported as failing if the export works without error
|
||
\begin_inset Flex URL
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
https://cmake.org/cmake/help/v3.0/command/set_tests_properties.html
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Add failing cases to this file, if they cannot be solved
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
immediately
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
but it is expected that the export will work in a foreseeable future, e.g.
|
||
low priority issues like failures to export to a non-target format (for
|
||
the manuals everything except pdf2).
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
The following sublabels are currently present in
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
invertedTests
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
:
|
||
\end_layout
|
||
|
||
\begin_layout Description
|
||
todo test failures that require attention:
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Itemize
|
||
minor issues to explore and properly sort later,
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
easyfix issues,
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
LyX bugs to report at trac (move pattern to section "lyxbugs" once done).
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Description
|
||
lyxbugs LyX bugs with a Trac number.
|
||
\end_layout
|
||
|
||
\begin_layout Description
|
||
ert Export failures due to "raw" LaTeX use in ERT or preamble code.
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Standard
|
||
"Wontfix" if demonstrating correct use and OK in the default output format.
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Description
|
||
texissues Export fails due to LaTeX limitations like non-ASCII characters
|
||
in verbatim or listings, incompatible packages, ...
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Standard
|
||
"Wontfix" if documents demonstrate correct use in the default output format:
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
If the source can be made more robust without becoming "hackish", fix the
|
||
source,
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
if LyX could be enhanced to care for a permanent TeX limitation, file a
|
||
ticket at trac and add a pattern under lyxbugs,
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
otherwise, add a pattern here.
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Description
|
||
attic Documents in the attic (kept for reference and format conversion test).
|
||
Usually
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
Wontfix
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
.
|
||
\end_layout
|
||
|
||
\begin_layout Subparagraph
|
||
suspended tests
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Test cases whose name additionally matches a pattern in the file
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
development/autotests/suspendedTests
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
get the label
|
||
\emph on
|
||
suspended
|
||
\emph default
|
||
(instead of
|
||
\emph on
|
||
export
|
||
\emph default
|
||
and
|
||
\emph on
|
||
inverted
|
||
\emph default
|
||
).
|
||
This means they are not executed using
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
ctest -L export
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
or
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
ctest -L inverted
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
.
|
||
However, they also get the test property
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
WILL_FAIL
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
, i.e.
|
||
they are reported as failing if the export works without error.
|
||
From time to time they still have to be checked using
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
ctest -L suspended
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
These tests are suspended, because the export fails for known reasons which
|
||
cannot ATM be resolved.
|
||
But it is expected the reason might disappear in the future.
|
||
Be it new TL or better handling in \SpecialChar LyX
|
||
.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
For ctest commands without the
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
-L
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
parameter nothing changes.
|
||
Suspended or not, tests will be executed depending only on the selecting
|
||
regular expression given to the ctest command (see
|
||
\begin_inset CommandInset ref
|
||
LatexCommand ref
|
||
reference "par:ctest-options"
|
||
|
||
\end_inset
|
||
|
||
).
|
||
\end_layout
|
||
|
||
\begin_layout Paragraph
|
||
\begin_inset CommandInset label
|
||
LatexCommand label
|
||
name "par:Unreliable-tests"
|
||
|
||
\end_inset
|
||
|
||
Unreliable tests
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Test cases whose name matches a pattern in the file
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
development/autotests/unreliableTests
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
get the label
|
||
\emph on
|
||
unreliable
|
||
\emph default
|
||
.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
These tests are not executed using
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
ctest -L export
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
or
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
ctest -L inverted
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
.
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
They pass or fail for various reasons not related to LyX (nonstandard, erratic)
|
||
or pass but should rather fail (wrong output).
|
||
|
||
\begin_inset Note Note
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
*invalid* tests (wrong output) are not *unreliable*.
|
||
# Use "unfit" or "unapplicable" as better label and name of pattern file?
|
||
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
The following sublabels are currently present in
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
unreliableTests
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
:
|
||
\end_layout
|
||
|
||
\begin_layout Description
|
||
nonstandard Documents with additional requirements, e.g.
|
||
a class or package file not in TeXLive.
|
||
|
||
\begin_inset Note Note
|
||
status open
|
||
|
||
\begin_layout Plain Layout
|
||
TODO: rename to
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
extra
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
or
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
exotic
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
?
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Description
|
||
erratic Tests depending on local configuration or the phase of the moon.
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Description
|
||
varying_versions Test depending on TeX distribution, package versions or
|
||
OS.
|
||
\end_layout
|
||
|
||
\begin_layout Description
|
||
wrong
|
||
\begin_inset space ~
|
||
\end_inset
|
||
|
||
output Export does not fail but the resulting document has (undetected)
|
||
errors.
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Standard
|
||
\paragraph_spacing single
|
||
\begin_inset Note Note
|
||
status open
|
||
|
||
\begin_layout Plain Layout
|
||
\paragraph_spacing single
|
||
These tests are in a strict sense not unreliable but
|
||
\emph on
|
||
invalid
|
||
\emph default
|
||
(not measuring what they should measure).
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Paragraph
|
||
\begin_inset CommandInset label
|
||
LatexCommand label
|
||
name "par:Export-test-filtering"
|
||
|
||
\end_inset
|
||
|
||
Export test filtering
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
The assignment of a label to a test is controlled by a set of files with
|
||
regular expressions that are matched against the test names.
|
||
\end_layout
|
||
|
||
\begin_layout Description
|
||
ignoredTests (small file)
|
||
\begin_inset Newline newline
|
||
\end_inset
|
||
|
||
Tests selected here are withdrawn in the configuration step (cf.
|
||
|
||
\begin_inset CommandInset ref
|
||
LatexCommand ref
|
||
reference "par:Configuring-ctests"
|
||
|
||
\end_inset
|
||
|
||
).
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Labeling
|
||
\labelwidthstring 00.00.0000
|
||
Input Test of any export combination
|
||
\end_layout
|
||
|
||
\begin_layout Labeling
|
||
\labelwidthstring 00.00.0000
|
||
Output Stop if tests not selected here
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Description
|
||
unreliableTests: Tests selected pass or fail dependent on the system where
|
||
the test is run.
|
||
Selected tests gain the label 'unreliable'.
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Labeling
|
||
\labelwidthstring 00.00.0000
|
||
Input Each test which passed 'ignoredTests'
|
||
\end_layout
|
||
|
||
\begin_layout Labeling
|
||
\labelwidthstring 00.00.0000
|
||
Output Stop if test selected, gain label 'unreliable'.
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\begin_layout Description
|
||
invertedTests
|
||
\begin_inset space \space{}
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Labeling
|
||
\labelwidthstring 00.00.0000
|
||
Input Each test which passed 'unreliableTests'
|
||
\end_layout
|
||
|
||
\begin_layout Labeling
|
||
\labelwidthstring 00.00.0000
|
||
Output Stop if not selected, gain test-property 'WILL_FAIL' (i.e.
|
||
tests are reported as failing if the export works without error.) If no
|
||
subselection applies, gain labels 'export' and 'inverted'.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
The following filter perfoms a subselection of 'invertedTests':
|
||
\end_layout
|
||
|
||
\begin_layout Description
|
||
suspendedTests Tests selected here gain the label 'suspended' but _not_
|
||
'export' or 'inverted', although in ctest they remain inverted.
|
||
('ctest' knows only 'inverted' or not, labels are used only for test selection)
|
||
\end_layout
|
||
|
||
\begin_deeper
|
||
\begin_layout Labeling
|
||
\labelwidthstring 00.00.0000
|
||
Input Each test selected by 'invertedTests'
|
||
\end_layout
|
||
|
||
\begin_layout Labeling
|
||
\labelwidthstring 00.00.0000
|
||
Output Selected test gains label 'suspended'.
|
||
|
||
\end_layout
|
||
|
||
\end_deeper
|
||
\end_deeper
|
||
\begin_layout Standard
|
||
The following table may clarify label assignement
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
\begin_inset Tabular
|
||
<lyxtabular version="3" rows="7" columns="9">
|
||
<features tabularvalignment="middle">
|
||
<column alignment="left" valignment="top" width="0pt">
|
||
<column alignment="left" valignment="top" width="0pt">
|
||
<column alignment="left" valignment="top" width="0pt">
|
||
<column alignment="left" valignment="top" width="0pt">
|
||
<column alignment="center" valignment="top">
|
||
<column alignment="center" valignment="top">
|
||
<column alignment="center" valignment="top">
|
||
<column alignment="center" valignment="top">
|
||
<column alignment="center" valignment="top">
|
||
<row>
|
||
<cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
Test matching pattern in file:
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
Assigned label
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell multicolumn="2" alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
test property
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
</row>
|
||
<row>
|
||
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
ignoredTests
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
unreliableTests
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
invertedTests
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
suspendedTests
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
export
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
unreliable
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
inverted
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
suspended
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
</row>
|
||
<row>
|
||
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
Yes
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
-
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
-
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
-
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
-
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
-
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
-
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
</row>
|
||
<row>
|
||
<cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
No
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
Yes
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
-
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
-
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
-
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
+
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
-
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
-
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
</row>
|
||
<row>
|
||
<cell multirow="4" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
No
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
Yes
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
Yes
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
-
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
-
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
-
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
+
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
WILL_FAIL
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
</row>
|
||
<row>
|
||
<cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
No
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
+
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
-
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
+
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
-
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
WILL_FAIL
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
</row>
|
||
<row>
|
||
<cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
No
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
-
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
+
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
-
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
-
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
-
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
</row>
|
||
</lyxtabular>
|
||
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
\begin_inset Note Note
|
||
status open
|
||
|
||
\begin_layout Plain Layout
|
||
Without the
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
suspendedTests
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
filter, this would be far less complicated:
|
||
\end_layout
|
||
|
||
\begin_layout Plain Layout
|
||
\begin_inset Tabular
|
||
<lyxtabular version="3" rows="6" columns="7">
|
||
<features tabularvalignment="middle">
|
||
<column alignment="left" valignment="top" width="0pt">
|
||
<column alignment="left" valignment="top" width="0pt">
|
||
<column alignment="left" valignment="top" width="0pt">
|
||
<column alignment="center" valignment="top">
|
||
<column alignment="center" valignment="top">
|
||
<column alignment="center" valignment="top">
|
||
<column alignment="center" valignment="top">
|
||
<row>
|
||
<cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
Test matching pattern in file:
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
Label
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
test property
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
</row>
|
||
<row>
|
||
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
ignoredTests
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
unreliableTests
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
invertedTests
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
export
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
unreliable
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
inverted
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
</row>
|
||
<row>
|
||
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
Yes
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
-
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
-
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
-
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
-
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
</row>
|
||
<row>
|
||
<cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
No
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
Yes
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
-
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
-
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
+
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
-
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
</row>
|
||
<row>
|
||
<cell multirow="4" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
No
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
Yes
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
+
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
-
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
+
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
WILL_FAIL
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
</row>
|
||
<row>
|
||
<cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
No
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
+
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
-
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
-
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
<cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
|
||
\begin_inset Text
|
||
|
||
\begin_layout Plain Layout
|
||
|
||
\end_layout
|
||
|
||
\end_inset
|
||
</cell>
|
||
</row>
|
||
</lyxtabular>
|
||
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
check_load tests
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
These tests check whether a .lyx file loads without any terminal messages.
|
||
They correspond to the manual operations of simply opening a .lyx file on
|
||
the terminal, exiting LyX once the file is loaded, and then checking whether
|
||
there is any output from the terminal.
|
||
These tests are useful for catching malformed .lyx files and parsing bugs.
|
||
They can also be used to find a .lyx file in which an instance of something
|
||
happens.
|
||
To do this, compile LyX with a local patch that outputs something to the
|
||
terminal when an instance is found, and then run the check_load tests to
|
||
see if any fail, which would mean that the situation occurs in the LyX
|
||
documentation files corresponding to the failed tests.
|
||
These tests are expectedly fragile: any LyX diagnostic message, which is
|
||
not necessarily an error, would cause the tests to fail.
|
||
Similarly, any message output by a library (e.g.
|
||
Qt) would also cause failure.
|
||
There are some messages that the check_load tests are instructed to ignore,
|
||
which are stored in the file
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
development/autotests/filterCheckWarnings
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Under cmake, the tests are labeled as 'load'.
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
Keytests
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Automated tests based on the "MonKey Testing" keytest program are enabled
|
||
if the necessary dependencies are found and if the CMake flag
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
-DLYX_ENABLE_KEYTESTS=ON
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
is used.
|
||
They are documented in the README document in
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
development/autotests
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
subfolder of the \SpecialChar LyX
|
||
source code distribution.
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
lyx21 tests
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
These tests combine lyx2lyx tests with check_load tests.
|
||
They fail if either fails.
|
||
\end_layout
|
||
|
||
\begin_layout Subsubsection
|
||
URL tests
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
The URL tests are enabled with the
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
-DLYX_ENABLE_URLTESTS=ON
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
CMake flag and are useful for finding broken links in our documentation
|
||
files.
|
||
If a URL test fails, to see which link in particular was reported as broken,
|
||
see the output in
|
||
\begin_inset Flex Code
|
||
status collapsed
|
||
|
||
\begin_layout Plain Layout
|
||
LastTest.log
|
||
\end_layout
|
||
|
||
\end_inset
|
||
|
||
.
|
||
These tests are extremely fragile (e.g.
|
||
a test can depend on your Internet connection) and a failed URL test should
|
||
not be taken too seriously.
|
||
URL tests are labeled as
|
||
\family typewriter
|
||
'url'.
|
||
\end_layout
|
||
|
||
\begin_layout Paragraph
|
||
Running URL tests
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
cmake is required to run the \SpecialChar LyX
|
||
tests, running them is not implemented for
|
||
autotools.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
The appropriate commands are:
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
|
||
\family typewriter
|
||
ctest -L url
|
||
\family default
|
||
|
||
\begin_inset Newline newline
|
||
\end_inset
|
||
|
||
runs all tests with label
|
||
\family typewriter
|
||
'url'
|
||
\end_layout
|
||
|
||
\begin_layout Itemize
|
||
|
||
\family typewriter
|
||
ctest -R 'check_.*urls'
|
||
\family default
|
||
|
||
\begin_inset Newline newline
|
||
\end_inset
|
||
|
||
runs the tests 'check_accessible_urls'
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Associated test results can be examined in ctest-log directory in files
|
||
of the form 'LastFailed.*URLS.log'
|
||
\end_layout
|
||
|
||
\begin_layout Section
|
||
Development policies
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
This chapter lists some guidelines that should be followed.
|
||
This list is not complete, and many guidelines are in separate chapters,
|
||
such as
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
When is an update of the .lyx file format number needed?
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
in Section
|
||
\begin_inset CommandInset ref
|
||
LatexCommand ref
|
||
reference "sec:When-is-an"
|
||
|
||
\end_inset
|
||
|
||
.
|
||
\end_layout
|
||
|
||
\begin_layout Subsection
|
||
When to set a fixed milestone?
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
Only set a fixed milestone (like 2.1.4 or 2.2.0) if at least one of the following
|
||
holds:
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
Somebody is actively working on a fix.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
The bug is so severe that it would block the release if it is not fixed.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
If a bug is important, but nobody is working on it, and it is no showstopper,
|
||
use a milestone like 2.1.x or 2.2.x.
|
||
For all other bugs, do not set a milestone at all.
|
||
\end_layout
|
||
|
||
\begin_layout Subsection
|
||
Can we add rc entries in stable branch?
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
No.
|
||
We are supposed to increase the prefs2prefs version number with such things.
|
||
\end_layout
|
||
|
||
\begin_layout Section
|
||
Documentation policies
|
||
\end_layout
|
||
|
||
\begin_layout Subsection
|
||
Rules
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
There are 6
|
||
\begin_inset space ~
|
||
\end_inset
|
||
|
||
rules in editing the docs:
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
\begin_inset CommandInset label
|
||
LatexCommand label
|
||
name "enu:If-you-are"
|
||
|
||
\end_inset
|
||
|
||
If you are not the maintainer of a doc file or a chapter/section, you MUST
|
||
use change tracking so that the maintainer could review your changes
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
Respect the formatting of the document.
|
||
The different files use different formatting styles.
|
||
That is OK and has historic reasons nobody fully knows ;-).
|
||
But it is important to be consistent within one file.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
All changes you make to a file in one language MUST also go the file in
|
||
the other actively maintained languages.
|
||
Normally the maintainer does this for you, if you are the maintainer, you
|
||
must do this by copying or changing the changed or added text to the other
|
||
files so that the translators sees the blue underlined text and know what
|
||
they have to translate and what was changed.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
You MUST assure that the document is compilable as
|
||
\begin_inset Quotes eld
|
||
\end_inset
|
||
|
||
PDF (pdflatex)
|
||
\begin_inset Quotes erd
|
||
\end_inset
|
||
|
||
or the document's default output format after your changes.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
All fixes (typos, compilation fixes, updates info etc.) go at first into
|
||
the current GIT branch because the user should benefit from all fixes with
|
||
every minor release.
|
||
Feel free to commit directly to branch as long as you follow rule
|
||
\begin_inset space ~
|
||
\end_inset
|
||
|
||
|
||
\begin_inset CommandInset ref
|
||
LatexCommand ref
|
||
reference "enu:If-you-are"
|
||
|
||
\end_inset
|
||
|
||
.
|
||
You can immediately commit to master as well.
|
||
\end_layout
|
||
|
||
\begin_layout Enumerate
|
||
The fileformat of a file must not be changed unless you document a new feature
|
||
in LyX that requires a new fileformat.
|
||
The reason for this rule is to keep it easy for the doc maintainers to
|
||
port/backport changes to from master/branch.
|
||
\end_layout
|
||
|
||
\begin_layout Standard
|
||
The main documentation consists of these files:
|
||
\end_layout
|
||
|
||
\begin_layout Description
|
||
splash.lyx it is the first file you see after an installation.
|
||
We assume that a new user sees this.
|
||
It is therefore designed to be as simple as possible.
|
||
Therefore please don't add any new formatting, only fix typos etc.
|
||
Splash.lyx is up to date for \SpecialChar LyX
|
||
2.1.x, currently maintained by Uwe Stöhr.
|
||
\end_layout
|
||
|
||
\begin_layout Description
|
||
Intro.lyx This is the manual new users will read to learn \SpecialChar LyX
|
||
.
|
||
It therefore uses a limited set of formatting.
|
||
For example a standard document class.
|
||
Since new users will first learn about the formatting possibilities of
|
||
\SpecialChar LyX
|
||
please keep this file that simple.
|
||
Intro.lyx is up to date for \SpecialChar LyX
|
||
2.1.x, currently maintained by Uwe Stöhr.
|
||
\end_layout
|
||
|
||
\begin_layout Description
|
||
Tutorial.lyx our tutorial.
|
||
It must be always up to date.
|
||
Normally there is nothing to add since we don't want to overwhelm new users
|
||
with too much details.
|
||
The will learn these details while using \SpecialChar LyX
|
||
and we have special manuals.
|
||
Tutorial.lyx is up to date for \SpecialChar LyX
|
||
2.1.x, currently maintained by Uwe Stöhr.
|
||
\end_layout
|
||
|
||
\begin_layout Description
|
||
UserGuide.lyx our main user guide.
|
||
It covers a mixture of basic and detailed information.
|
||
Some information is also in the Math and EmbeddedObjects manual so that
|
||
the UserGuide refers to these files.
|
||
UserGuide.lyx is up to date for \SpecialChar LyX
|
||
2.1.x, currently maintained by Uwe Stöhr.
|
||
\end_layout
|
||
|
||
\begin_layout Description
|
||
EmbeddedObjects.lyx a special manual to explain things like tables floats
|
||
boxes etc.
|
||
in all detail.
|
||
EmbeddedObjects.lyx is up to date for \SpecialChar LyX
|
||
2.1.x, currently maintained by Uwe
|
||
Stöhr.
|
||
\end_layout
|
||
|
||
\begin_layout Description
|
||
Math.lyx a special manual to explain everything regarding math in all detail.
|
||
Math.lyx is up to date for \SpecialChar LyX
|
||
2.1.x, currently maintained by Uwe Stöhr.
|
||
\end_layout
|
||
|
||
\begin_layout Description
|
||
Additional.lyx this manual covers information that would be too much detail
|
||
for the UserGuide or would make the UserGuide uncompilable or only compilable
|
||
when installing a lot of special \SpecialChar LaTeX
|
||
-packages.
|
||
What should be in the UserGuide or better in Additional is a matter of
|
||
taste.
|
||
it is up to you to decide that.
|
||
Additional.lyx is not completely up to date for \SpecialChar LyX
|
||
2.1.x.
|
||
Only chapter
|
||
\begin_inset space ~
|
||
\end_inset
|
||
|
||
8 is up to date and currently maintained by Uwe Stöhr.
|
||
It certainly needs a rewrite and update.
|
||
For example many info in chapter
|
||
\begin_inset space ~
|
||
\end_inset
|
||
|
||
2 and 3 are already covered by the UserGuide and/or the EmbeddedObjects
|
||
manual.
|
||
\end_layout
|
||
|
||
\begin_layout Description
|
||
Customization.lyx this manual covers information how to customize \SpecialChar LyX
|
||
for certain
|
||
output formats, operating systems, languages etc.
|
||
It is currently completely out of date and needs a major rewrite and update.
|
||
If you do this please assure that your information are given for all OSes
|
||
and \SpecialChar LaTeX
|
||
distributions (meaning be as objective as possible).
|
||
\end_layout
|
||
|
||
\end_body
|
||
\end_document
|